This chapter describes the services that you can enable on the ME platforms.
There are administrative services available on the ME master that are enabled by default. These master services are:
Cluster-Master Services
Directory Services
Accounting Services
Authentication Services
ME Database
Registration Services
Server Load
Call Failover (Signaling and Media)
Load-Balancing
File-Mirror
Route Server
Sampling
Third-Party-Call-Control (3PCC)
If you are not using any of these services, you can globally disable them to conserve memory and system resources on the ME master.
The cluster-master services object configures the ME system that maintains the master configuration for the cluster. The master is responsible for providing configuration changes and updates to other devices in the cluster. If a different device becomes the cluster-master during a failover, this device then sends out its configuration to the other devices in the cluster.
When enabled, accounting services supports RADIUS accounting, system logging (syslog), DIAMETER protocol services, the accounting database, archiving, and the accounting file-system.
You can configure one or more of these accounting mechanisms for capturing the ME network accounting activity and SIP call detail records under the VSP (Virtual System Partition) configuration object.
The following session enables the ME global accounting services on the master.
NNOS-E> config master-services config master-services> config accounting config accounting> set admin enabled config accounting> set host-box cluster box 3 config accounting> set host-box cluster box 1 config accounting> set group 1
The master-services database object allows you to configure maintenance and other settings for the ME system database. The database is the local repository for call accounting records and media files.
The master-services server-load object configures the ME to calculate server load. This object must be enabled if your dial plan arbiter settings use least-load as the routing algorithm option. (The arbiter rules property sets the criteria by which the ME selects the server to which it forwards calls.)
The master-services call-failover object configures failover for both the media and signaling streams across an ME cluster. Enabling call-failover ensures that there is an active copy of the database on another box in the cluster in the event of a failure. The first host-box property defines the primary ME system. Configure backup boxes in the event of primary failure by re-executing the host-box property.
The following session enables call-failover of the media and signaling streams.
NNOS-E> config master-services config master-services> config call-failover config call-failover> set admin enabled config call-failover> set host-box cluster box 1 config call-failover> set host-box cluster box 2
The call must be connected at the SIP level for signaling failover to succeed. States prior to the ”connected” state are not maintained in the cluster-wide state table. For TCP and TLS connections, the user agent (UA) must reestablish the connection after the failover, since TCP and TLS are connection-oriented protocols that do not maintain state information. If TLS is used, the appropriate certificate must be loaded on both devices in the cluster.
Accurate call logs are recorded at the end of the call. However, if the ME system maintaining the call log database fails over to the other ME system in the cluster, call information will not be recorded.
Use the ME show signaling-sessions action to view cluster-wide signaling state information.
NNOS-E> show signaling-sessions
session-id: 342946641025485482
fromURI: <sip:1234@dial-plan.com>
toURI: <sip:5678@dial-plan.com>
inLegCallID: 3c2a54ca1fbd-7intxouoq8zo@172-30-0-176
inLegFromTag: xqkhmbwmiv
inLegToTag: b432a8c0-13c4-454a1124-102dd42a-164adf67
outLegCallID: CXC-279-61b29378-b432a8c0-13c4-454a1124-102dd42b-7023adbd@dial-plan.com
outLegFromTag: b432a8c0-13c4-454a1124-102dd42b-749c0b03
outLegToTag: 152jkzyt73
origInFromURI:
origInToURI:
origOutFromURI:
origOutToURI:
vthreadID: 278
initialMethod: 0
Box: 0.0.0.0
The master-services load-balancing object configures the ME systems to host the load-balancing master service. These devices (boxes) are responsible for keeping the rule database up to date. They do not need to be the same devices that host the head-end interfaces, although it is common to do so. (You can, for example, configure devices in the cluster that only serve as host devices without any head-end interfaces or backing interfaces.)
For more information on the load-balancing object, refer to the Oracle Communications WebRTC Session Controller Media Engine Object Reference. For more information on configuring load-balancing across ME interfaces, see Load Balancing Across ME Interfaces.
The following CLI session enables load balancing on the master, specifies box 1 as the master box on which the rule database runs (subsequent host boxes 2 and 3 serve as backup) and associates the load balancing service with preconfigured VRRP group 1.
NNOS-E> config master-services config master-services> config load balancing config load-balancing> set host-box cluster box 1 config load-balancing> set host-box cluster box 2 config load-balancing> set host-box cluster box 3 config load-balancing> set group 1
The master-services sampling object opens the mechanism for setting the interval at which the ME samples operational aspects of the system for either:
Display in the ME Management System, or
For sending to an IBM Tivoli server.
By setting sampling for a status provider, you can view data for that provider over a specified period of time. The ME supports two sampling targets: a Postgres SQL database and an IBM Tivoli server. (Set the provider data sent to the target using the status and provider objects. See Oracle Communications WebRTC Session Controller Media Engine Object Reference for more information on configuring these objects.)
When you execute a status-provider command from the CLI, the system just displays the results of the request at the time it was issued.
Once you have enabled sampling, the master service stores the samples in its local database. You can select a status provider underneath Trends in the Status tab of the ME Management System. The GUI trends graphs pull data from the database on the sampling master service box to display a time series graph of the results. Changes to the interval setting in the sampling subobjects do not effect the CLI results.
Note:
If you have limited storage space, and are not using this feature, disable it. Otherwise, polling data is continuously written to the status database.The following CLI session enables sampling services on the ME master:
NNOS-E> config master-services config master-services> config sampling config sampling> set admin enabled config sampling> set host-box cluster box 1 config sampling> set host-box cluster box 2 config sampling> set host-box cluster box 3 config sampling> set group 1 config sampling> return config master-services> return config>
The ME event logger allows you to configure how event messages are filtered and captured. You can direct event messages to a remote syslog server (by IP address), to a named event log file stored on the ME system, or to the local ME database.
The following session configures the event logger to direct event messages to a remote syslog server.
NNOS-E> config services config services> config event-log config event-log> config syslog 192.168.124.89
The following session configures the event logger to direct event messages to a named file and sets the event log operational parameters: direct all messages to the file, limit the event log file size to 20 Mbytes, and set the maximum number of event log files to create when log files reaches the maximum size in megabytes.
NNOS-E> config services config services> config event-log config event-log> config file eventfile1 config file eventfile1> set admin enabled config file eventfile1> set filter all error config file eventfile1> set size 20 config file eventfile1> set count 5
The following session configures the event logger to direct event messages to the local ME database and sets the event log operational parameters: direct only SIP messages to the local database, and set the maximum number of days over which event messages are logged to the local database before the database is cleared and restarted.
NNOS-E> config services config services> config event-log config event-log> config local-database config local-database> set admin enabled config local-database> set filter sip error config local-database> set history 50
The services/monitors configuration object allows you to monitor the following statistics and thresholds for logging and SNMP trap generation:
CPU usage
Memory usage
TLS connections statistics
Polling intervals are in minutes, memory and CPU usage in percent, and TLS connections and failures in actual numbers. At the specified polling interval(s), the ME checks memory and CPU usage, and TLS statistics. If a parameter setting is exceeded, the ME logs an event and an SNMP trap.
NNOS-E> config services config services> config monitors config monitors> config monitor usage Creating ’monitor usage' config monitor usage> set interval 60 config monitor usage> set parameter cpu-usage 90 config monitor usage> set parameter memory-usage 95 config monitor usage> return config monitors> config monitor tls Creating 'monitor tls' config monitor tls> set interval 30 config monitor tls> set parameter tls-connections 1000 config monitor tls> set parameter tls-failures 10
The services/data-locations configuration object allows you to specify the directory and path locations on the ME system where you are to save certain types of information. This information includes:
RTP media (for call recording). Use the rtp-recorded property to select a location on the system disk for local archiving of call detail records and call recordings.
RTP mixed (for playback of recorded calls). Use the rtp-mixed property to set the location for playback of recorded calls.
File transfer. Use the file-transfer-recorded property to set the location for file transfer records.
Log files. Use the log property to set the location for log files.
If you choose not to create specific locations for saved files, the ME provides default directory path locations. For example, the directory path /cxc_common on hard-drive-1 is the default location for recorded RTP files and file transfers. You can display the default directory file paths using the show command.
config> config services data-locations config data-locations> show services data-locations rtp-recorded[1] /cxc_common/rtp_recorded rtp-recorded[2] /cxc/recorded rtp-mixed[1] /cxc_common/rtp_mixed rtp-mixed[2] /cxc/mixed rtp-mixed[3] /cxc/admin/archives file-transfer-recorded[1] /cxc_common/ft_recorded file-transfer-recorded[2] /cxc/recorded log /cxc_common/log
The following CLI session changes the default logging path from /cxc_common/log to /cxc/admin/logfiles.
config> config services data-locations config data-locations> set log /cxc/admin/logfiles
The following CLI session sets the location for ”mixed” RTP files to the directory /cxc/admin/RTPmixed; the location for storing file transfer records is set to /cxc/admin/FTrecords.
config> config services data-locations config data-locations> set rtp-mixed /cxc/admin/RTPmixed config data-locations> set file-transfer-recorded /cxc/admin/FTrecords
If you want to use a database other than the one that is provided with the ME system, you can configure the ME to use an external database to store event logs, call detail records, and other accounting data. Depending on your network remote SQL server databases, for example, can provide large storage and resource capabilities.
To configure an external database, you will need the Open Database Connectivity (ODBC) driver name associated with the database, as well the user name and secret tags (and password) needed for the ME to access the database. Consult your database administrator for this information before configuring the remote database on the ME system.
The following CLI session configures the database driver named ”My SQL Server” and sets the username, secret-tag, and password/password confirmation for this database.
config> config services database external config database external> set driver ”My SQL Server” config database external> set username cxc config database external> set secret-tag 123 password: ********* confirm: ********* config database external>
The following CLI session configures the event log to direct snmp events with the severity warning to the SQL database named corpDatabase for a period of 150 days. The ME automatically associates the external database name to the services/database configuration.
config services> config event-log config event-log> config external-database corpDatabase config corpDatabase> set admin enabled config corpDatabase> set filter snmp warning config corpDatabase> set history 150
For more information on the services/database object, refer to the Net-Net OS-E – Objects and Properties Reference.
The storage-device object allows you to set warning and failure thresholds for remaining disk space on ME hard drives. When a disk drive reaches the configured fail-threshold property setting, the ME begins WRITE operations to the next available disk drive. Warning messages are logged (in minutes) whenever disk threshold settings are matched.
The storage-device object operates on all installed disk drives. If all disk drives match the configured thresholds, media call recording, file transfers, and log files will no longer be written to the ME disks.
Note:
Currently, the ME systems support two 250GB internal disk drives.The following CLI session sets the fail thresholds for all installed disk drives. Writing to that disk fails when the remaining disk space drops to 20 GB.
The ME can automatically perform tasks on a configured schedule. This means that you do not have to physically execute an action at a specific time; the ME does it for you. Use the set action ? command to display the current list of tasks from which you can choose.
The following CLI session configures a directory reset for the Boston1 enterprise directory at 3 pm.
config> config services config services> config tasks config tasks> config task directoryReset config task 1> set action ? archive Run the archiving task for a given vsp directory-reset Reset an enterprise directory config task 1> set action directory-reset config task 1> set schedule time-of-day 15:00:00
The ME automatically runs a database maintenance script daily, at 3:00 A.M. This ”normal” database maintenance purges (removes old files preventing ME disks from becoming too full), ”vacuums” (reclaims unused disk space), reindexes, and analyzes the database. You can also selectively schedule periodic database maintenance or force database maintenance at any time.
Along with normal daily database maintenance, Oracle recommends that you perform a ”vacuum-full” on the database monthly to reclaim unused disk space.
This section describes how to do the following database maintenance tasks:
Set normal maintenance time-of-day.
Schedule periodic database maintenance.
Force manual database maintenance.
Perform the database ”vacuum-full” process (recommended monthly, in addition to normal maintenance).
Note:
As a guideline, Oracle recommends that you perform database archiving more frequently than database maintenance. For example, archiving on a daily basis and performing maintenance every 7-days allows records in the database to age without the risk of removing records before those records are archived. See Enabling and Configuring Local Archiving for information.The ME automatically runs database maintenance daily, at 3:00 A.M.
If you want to change the actual time-of-day when the ME runs normal database maintenance, use the master-services database object. If old records are found, the ME purges those records from the database. Optionally, you can configure a time period in hours, such as every 3 hours, if you want run maintenance at multiple time periods during a 24-hour day.
To verify that normal maintenance has successfully completed, and that a table has been vacuumed automatically, view the system log file. The log file should display a message similar to the one shown below:
2008-04-16T05:39:45+12:00[notice] 1:SIP[system] An automatic VACUUM FULL was performed on database table SipMessage to reclaim 895300 unused pointers
The VSP database object allows you to configure the number of days to elapse before the ME purges old records from the database. You can selectively configure the number of days for each of the following database records:
accounting
call details
media
file transfer
instant messages
Whenever records in the database become older than the configured number of days, the next maintenance natively purges the old files. The following CLI session configures the number of days to elapse for each database record type before the ME deletes the old records from the system disk.
Use the database-maintenance normal command to run a specific database maintenance operation at any time. This forces a database cleanup of any old database entries if you did not previously configure the VSP database settings. Use the show database-tables command to display the database contents after the cleanup.
CLI Session
NNOS-E>
database-maintenance normal
Starting database maintenance as a background operation.
-- this may take a very long time --
Please check database-maintenance-status for notification when this operation is complete.
The normal (daily) vacuum process attempts to reclaim any unused space in the database (this is analogous to a hard drive defragmentation process, but on the database files) without locking any of the tables.
The database vacuum-full process locks each table, one at a time, and reclaims all possible disk space. Note that a table lock prevents the table in question from being written to by an application; i.e. the ME.
Oracle recommends performing a database vacuum-full on a monthly basis by scheduling a ”maintenance/outage window.” You should only run the process during a maintenance window because the process will lock tables, preventing them from being written to by the ME. This can affect the ability of a DOS rule from being triggered, and at the same time, affecting call-logs, recording of accounting data, and any other data that is written to the database. (However, running database vacuum-full will not affect the ability of the ME to pass sip/media traffic, accept/delegate registrations, route calls, and perform other directly service-related tasks).
If your site is logging a large volume of data, you may wish to perform a vacuum-full on a more frequent (e.g. weekly) basis.
Note the following database vacuum-full implementation tips:
You perform a vacuum-full on the entire database (global) using the database vacuum-full system command.
You vacuum a specific table using the database vacuum-full system <table-name> command. For example, you may wish to use this process if the ME logs a message stating that a specific table needs to be vacuumed.
You use the VSP database object to perform other database maintenance tasks, as described below:
delete: Purges the database of entries contained in the specified database, or entries in the table within the database. The database delete action (without qualifiers) deletes all rows in all tables in the database.
vacuum: Based on SQL's VACUUM command, reclaims storage occupied by deleted entries and makes it available for re-use. The system can read and write to the table while the process is occurring (versus more extensive vacuum-full process during which the table is not available for read/write operations during the process).
drop: Deletes all data stored in the specified table and removes the table definition from the database schema.
repair: Initiates database repair options. If you select the data-recovery option, the system recovers data that was removed by the ME when it corrected a corrupted database. The translate option migrates earlier databases to a format compatible with ME Release 3.2 and later.
initialize: Deletes all data and reinitializes the database.
snapshot: Captures an archive of the database at a certain point(s) in time.
Refer to the Net-Net OS-E – Objects and Properties Referencefor full description of how to use each of these database objects.
This section describes ways to manage the size of the ME database. That is, it describes ways to reduce the amount of data that is being written to the database. You may wish to try one of these procedures if your database is growing too large, or if it is responding too slowly:
Disable the logging of REGISTER messages.
Configure a policy to prevent logging of NOTIFY messages.
Note:
Backup the current ME configuration before attempting any of the procedures described in this section.To disable the logging of REGISTER messages in order to reduce the amount of data store in the database, do the following steps:
From the ME Management System, select vsp->default-session-config-> log-alert.
Set message-logging to no-registers, then click Set to save your changes. This change will take effect immediately.
Repeat Step 1 for any session-configs that have a log-alert configured (e.g. in session-config-pool entries, policies, dial/registration-plans, etc.).
To verify that REGISTER messages are no longer being logged, do the following steps:
From the ME Management System, click on the Call Logs tab.
From the left side of the window, click SIP Messages.
Click on Advanced Search.
Enter in REGISTER in the Request Message field.
The ME searches for messages of type REGISTER. None should be found.
If you want to further reduce the amount of data that is being logged to the database, you can configure a policy to prevent logging of specific message types. For example, you may want to prevent the logging of NOTIFY messages that are received from phones (i.e. being received on the public IP interface). These messages are often used as ”keep-alive” messages from the end device.
To configure a policy to prevent logging of NOTIFY messages from phones, do the following steps:
From the ME Management System, select vsp->policies.
Scroll to session-policies, then click Add policy.
Name the new policy ”default” and then click Create.
If there is already a default-policy configured under vsp->policies skip to step 4, keeping in mind that in this example the default-policy is named ”default.”
Specify the ”default” policy as your default-policy under vsp->policies-> session-policies.
Under vsp->policies-> session-policies->policy default, add a new rule. Name the new rule something obvious, for example, ”NoLog-NOTIFY.”
Under vsp->policies-> session-policies->policy default->rule-> NoLog-NOTIFY, configure the condition-list as follows:
Set the default operation to AND
Set the mode to evaluate
Under vsp->policies-> session-policies->policy default->rule-> NoLog-NOTIFY->condition list, add a sip-message-condition, as follows:
Set an attribute of request-method
Set the match to match
For the request-method, select NOTIFY (You could also select other SIP message types.)
Under vsp->policies-> session-policies->policy default->rule-> NoLog-NOTIFY->condition list, add a sip-message-condition, as follows:
Set an attribute of local-ip
Set the match to match
For the local-ip, enter the IP Address of the ME public interface, including the ”slash” subnet mask notation. For example: 1.1.1.1/32.
Under vsp->policies->session-policies->policy default->rule-> NoLog-NOTIFY->condition list, add a sip-message-condition, as follows:
Set an attribute of direction
Set the match to match
For the value, select RX
Under vsp->policies-> session-policies->policy default->rule-> NoLog-NOTIFY, create a session-config container.
Under vsp->policies-> session-policies->policy default->rule-> NoLog-NOTIFY->session-config, configure a log-alert container, then set message-logging to disabled.
To check to see if the rule is being enforced, perform a ”show rules” from the CLI. For example:
NNOS-E> show rules name: policy default/rule NOTIFY admin: enabled evaluations: 10008082 successes: 8336316 NNOS-E> show rules name: policy default/rule NOTIFY admin: enabled evaluations: 10008127 successes: 8336356
If the number of ”successes” is increasing, then the condition-list ”entry criteria” are causing SIP messages to be affected by the rule's session-config.
The database-backup backup command allows you to create a backup file of the database, and save it to the ME.
Note:
Performing the database backup procedure increases the load on the ME, slowing down the device. Therefore, Oracle recommends performing this task for debugging purposes only.The database backup file is saved in /cxc/pg_dump/name, where name is the file name that you specify. When you enter the name for the backup database file, make certain to specify a path that begins with /cxc/pg_dump/.
For example, /cxc/pg_dump/database1 is correct. However, if you specify /cxc/database1, the operation will fail.
Note that by default the ME uses BZIP2 compression. This format is optimized for size, but can take longer to produce. If you would prefer to use GZIP compression, which is faster but results in a 30-40% larger archive, you can do so by supplying the gz suffix when you initiate the action. The following table provides examples of using the gz suffix :
Enter this filename at the command line | Get an archive of this type |
---|---|
DBbackup |
DBbackup.bz2 |
DBbackup.gz |
DBbackup.gz |
To create a database backup file and store it on the ME, perform the following steps:
Use the show mounts command and shell command to verify that you have enough storage space on the disk (preferably /mnt/hd2), as shown in the following sample CLI session:
NNOS-E> show mounts device device-name mount-point filesystem disk-size percent-free ------ ----------- ----------- ---------- --------- ------------ cdrom /dev/cdrom 0 0 usb /dev/usb1 0 0 hard-drive-1 /dev/root / reiserfs 234448 96 hard-drive-2 /dev/sdb 0 0 hard-drive-3 NNOS-E> shell bash-3.00# du -sh /var/lib/pgsql 296M /var/lib/pgsql bash-3.00# exit exit
You must create the /cxc/pg_dump directory due to the fact that this procedure is used most often as a debugging tool and is not present during the initial ME installation. Use the mkdir command as shown in the following CLI session:
NNOS-E> shell bash-3.00# mkdir pg_dump bash-3.00# exit exit NNOS-E>
Execute the database-backup backup command, specifying a filename for the database backup file.
For example, the following CLI session creates a database backup file named DBbackup.bz2 where system is the system database where call logs and accounting records are stored:
NNOS-E> database-backup backup system /cxc/pg_dump/DBbackup Are you sure (y or n)? Starting database backup as a background operation. -- this may take a very long time -- Please check database-maintenance-status for notification when this operation is complete.
Use the database-backup restore command to restore a saved database backup file from the /cxc/pg_dump directory to the ME system.
Any restore action adds entries from that file to the database. If your goal is to overwrite the database, then you should first use the database delete action, and then use the database-backup restore action.
The following CLI session restores the backup file backup.bz2.
CLI Session
NNOS-E> database-backup restore system /cxc/pg_dump/backup Are you sure (y or n)? y Starting database restore as a background operation. -- this may take a very long time -- Please check database-maintenance-status for notification when this operation is complete.
Local archiving allows you to store call accounting records and media files at regular intervals on the ME platform before the records are removed by the database maintenance interval, as described in the previous section. Other archiving options ”push” the data to alternate locations.
You can specify the types of information to store with the include- properties. If you do not include any of the message types, the archive will contain just the meta data (To, From, setup/connect/disconnect times, and call ID). All message types are included by default.
When archiving, the ME creates both a .zip file and an XML file of the archive contents. The XML file contains all of the XML data for the call except for the SIP messages. The .zip file contains the XML file and an additional file called sip.xml,which contains the SIP messages.
You enable local archiving using the vsp\accounting\archiving object. In addition, you must configure a server in one of the archiving sub-objects for the archiving mechanism to work.
• windows-share
• ftp-server
• smtp-server
• db-server
• local
The following CLI session enables archiving on the ftp server named ftp1.
NNOS-E> config vsp config vsp> config accounting config accounting> config archiving config archiving> config ftp-server ftp1 config ftp-server ftp1> set admin enabled config ftp-server ftp1> set username admin config ftp-server ftp1> set password-tag xyz123abc password: ************ confirm: ************ config ftp-server ftp1> set directory /archives config ftp-server ftp1> set server 192.168.10.10 config ftp-server ftp1> set port 1998 config ftp-server ftp1> set timeout 100000
To locally archive on a scheduled basis, you need to schedule the archiving task.
config> config services config services> config tasks config tasks> config task archive config task archive> set action archive config task archive> set schedule time-of-day 15:00:00
For more information on archiving and archiving to multiple server locations away from the ME system, refer to Chapter 5, ”Configuring ME Accounting and Archiving,” and the Oracle Communications WebRTC Session Controller Media Engine Object Reference.