Admin settings
From Pbxnsip Wiki
If you do not find what you are looking for related to the system administration, please check out the earlier version pages
System Administrator
Contents |
General
This section explains some of the general system-wide settings for the pbxnsip IP-PBX
System Name: The "System Name" fields lets the user to set a name for the PBX. This name is used in several places to identity the PBX. For example, when the PBX sends out emails that contain performance information about the PBX, the name will be placed the subject line of the e-mail.
Default IVR Language: This represents which language prompts are played during voice-mailbox and auto-attendant interaction. Based on the available 'audio_xx' directories, you will see a drop-down list of available languages here.
Default Tone Language: Most of the countries have their own ringback and busy tones. By placing the proper files in audio_xx directory and selecting the respective language name, you can play the country specific tones.
Default Web Language: If you want to interact with the PBX in your language? No problem. Select any language from the list of the languages from the drop-down list. Logout and login. You will see the web pages in the selected language.
For more information, see Localization. Image:Needhelp.gif
Administrator Login
It is very important that the system administrator login is protected. Therefore, you should set a reasonable safe password for the administrator login. The password is stored in a hashed format, so that there is no way of reading the password from the Global Configuration File.
Username: This is the administrator's login user name. By default, the username is "admin"
Password: This is the password for the above user name. By default, there is no password.
If you forgot your password, you need to manually edit the Global Configuration File and erase the "pw_pass" setting there. After this, you need to restart the PBX.
Appearance
Probably, not the correct heading for this section. Anyways, we kept this for the backward compatibility :-).
Web Session Timeout (s): This field decides how long a web session should stay active before it times out. The duration is set in seconds and the default value is 3600 (1 hour).
Password Strength: This field decides what kind of passwords users can have. The default is "Accept All Passwords". But it is advisable to have at least "Medium Security". The other option is "High Security".
Default CDR listing size: This field tells the system how many CDR records to display on the web interface. This setting should avoid that the user gets too many CDR on the display at a time. The default is set to 30.
Keep CDR Duration: This setting defines how long the CDR are kept in the database. By default, this setting is 7 days. The duration is expressed in time unit. A time unit may seconds (put a 's' behind the number), minutes (put an 'm' behind the number), hours (put a 'h' behind the number) or days (put a 'd' behind the number). An example would be "10d", meaning that the CDR are kept for ten days.
SOAP Trusted IP: This field is available only if the license key contains a SOAP flag. This field controls SOAP request coming from random addresses. You can specify the IP address or the host names here. If you want to allow multiple system to send SOAP requests, you can enter them here separated by space.
CDR URL: This field is available only if the license key contains a SOAP flag. This field controls where the CDRs are written. pbxnsip IP-PBX can write CDRs to a SOAP destination, MySQL database, CSV file etc.
SOAP CDR: set this field with "cdr:192.168.1.2:10000", where 192.168.1.2:10000 is the IP:Port of the SOAP CDR server.
CSV CDR: Set this field with "file:disk".
MySQL CDR: Set this field with "sql:192.168.1.2:10000" where 192.168.1.2:10000 is MySQL server;s IP:Port. If you are running MySQL on the default port, then you can use "sql:192.168.1.2".
Recording Location: This field defines where calls are being recorded. For more information about Recording, see the page Recording. Image:Needhelp.gif
Compress Recording: If this field is set to "On", the PBX will compress the recordings using GSM codec. Otherwise, the files will be saved as 16bit/sample.
Performance
This section lets the administrator to set some of the performance related settings.
Maximum Number of Calls: This setting defines how many calls the system allows at the same time. Because every call takes a certain portion of the available CPU, allowing too many calls will affect the quality of all ongoing calls. By limiting the number of calls on the CPU, you can reject calls that would otherwise potentially degrade the overall performance. On modern PC, you may have hundred or more calls running on one computer; however on embedded system you will probably have much less CPU power and the probability that you are running out of CPU power is much higher.
Processor Affinity Mask: This field lets the administrator to assign a particular CPU to the PBX process. For details, refer Processor Affinity
Maximum Duration of Call Recording sets an upper limit to call recordings. This setting is important because recording files might become very large and can cause problems with the system performance. There is another setting that limits the recording of a mailbox message, which is a domain setting.
Max. size of a configuration backup file: This setting decides what should be the maximum size, in bytes, of the backup file. The default is 1MB. If your PBX has a lot of data to be backed up, increase this value. The backup feature through the PBX web interface is mostly used in the CS410 (embedded system, where the file access is primitive). On other system, it is advisable to use the OS file manager to do the backup.
Max. number of concurrent registrations per extension: This setting controls how many user agents can be registered against an extension.
Minimum Registration Time (s): In a SIP environment, the registrar determines how long a user agent may be registered. Short registration times have a negative impact on the performance, but make sure that the user agents stabilize quickly after they lost connection to the PBX. This setting defines the lower limit for the registration time. The default is 30 seconds.
Maximum Registration Time: This used to define the upper limit for the registration time. The default value is 360 seconds
UDP NAT Refresh (s): If the registering user agent is behind NAT, the PBX uses this settings to control the registration. The PBX registers agents that use the UDP transport layer only for a short time, so that the user agents will re-register quickly and keep the NAT bindings alive this way. Typically the settings for UDP should be in the range from 15 to 45 seconds. The default is set to 30 seconds.
TCP/TLS NAT Refresh (s): This is similar to UDP NAT refresh setting. Since TCP/TLS connections don't need to refresh the bindings so often, a value of a few minutes are ok in most situations. The default is set to 180 seconds (3 minutes).
Maximum call duration: This setting sets the upper limit for the call duration. By default the setting is two hours(7200 seconds), but you might make it longer if you have long phone calls. This setting is good to keep your call list clean, for example if one mailbox talks to another mailbox.
More information about the registration procedure can be found in Registration Duration.
SIP Settings
This section defines few SIP related settings.
Use Short SIP Headers: SIP specifies for certain headers a short form. Short headers have the advantage to save some space in the messages, which reduce the overall probability that you run into problems with maximum message size in UDP. Although it is very simple to support this, some devices are not able to deal with the short headers. Therefore, the PBX offers both short and long headers. In order to maximize interoperability, the default value is set to "Long". If you are running into UDP packet fragmentation problems (message size above 1492 bytes), you should switch to the short header form.
Listen to sip.mcast.net: SIP also has it's own multicast group. Usually a SIP device knows where to send the requests; however during boot-up and configuration, a user-agent might want to locate the PBX with a multicast request. Therefore, the PBX offers the setting Listen to sip.mcast.net. If this setting is turned on and you are using user-agents with the multicast detection feature, you can just plug the devices into the network and they will get their configuration information automatically from the PBX.
Allow domain admin to change trunks: In hosted environments, the service provider might want to set the trunks up and hide this feature from his customers. If Allow domain admin to change trunks is set to "no", then the domain administrators will not be able to edit the trunks.
Allow domain admin to change dial plans: If this is set to 'no', then the domain administrators cannot change the dial plans.
Loopback detection: When the PBX starts a call, that same call may come back to the PBX, creating a loop. This is a dangerous situation, because it might initiate the same call again and again, ending up in many calls that take a lot of resources. Therefore, the PBX must detect such a loop. In environments where an external SIP proxy routes the call from one PBX domain to another, a simple loop back detection based on the call-id is too pessimistic. Therefore, in such environments you might want to allow such calls and turn the loop back detection off.
Inband DTMF detection: When a user presses a key on the telephone, the PBX must be able to understand that key press. In telephony system, this mechanism is typically called DTMF (see http://en.wikipedia.org/wiki/DTMF). In VoIP, DTMF should usually be sent via the out-of-band method (RFC2833), which makes it easy and failsafe for the PBX to detect those tones. However, there are some devices, do not support this method yet. In this case, the PBX must decode and analyze the media stream and perform this detection. This is erroneous and costs additional CPU performance. It is strongly recommended not to use this feature and to replace devices which do not support out-of-band with devices that do.
Remote SIP management: In environments where the service provider controls the PBX from a centralized location, the setting "Remote SIP management" is used to allow the provider to send commands to the PBX (for example, for re-reading the configuration). By default this setting is off, but if you are using such an environment this setting needs to be turned on.
License
In order to use the PBX, you need to have a license. The PBX offers several options for product licensing. You can request a demo license or permanent license from pbxnsip sales team. Once you received the license code, just copy the license code into the "License Code" field and hit the "Save" button.
Licenses Policy
Licenses can be permanent or temporarily. If you buy a license, they are typically permanent; for demonstration licenses, we usually provide temporary keys.
It is pbxnsip’s license policy to bind licenses to the addresses of a specific host. Therefore, you need to provide us the address of the host that you want to use with the PBX.
- MAC addresses are generally used to uniquely identify a computer. For CPE installations, MAC addresses must be used.
- IP addresses are used in hosted environments where it is difficult to license specific MAC addresses (server farms and redundancy).
Features
The license generator can have the following parameters:
- calls <number>: Limit the number of calls. A call can consist of several legs, for example during hunt group forking. The number of calls may be limited by the performance check. The default is no limit.
- accounts <number>: Limit the number of accounts. A account is anything that shows up in the Accounts/Show list (including CO-lines).
- domains <number>: Limit the number of domains. If not set, unlimited.
- extensions <number>: Limit the number of extensions. If not set, unlimited.
- attendants <number>: Limit the number of attendants. If not set, unlimited.
- callingcards <number>: Limit the number of callingcards. If not set, unlimited.
- hunts <number>: Limit the number of hunts. If not set, unlimited.
- hoots <number>: Limit the number of paging groups. If not set, unlimited.
- srvflags <number>: Limit the number of service flags. If not set, unlimited.
- ivrnodes <number>: Limit the number of IVR nodes. If not set, unlimited.
- acds <number>: Limit the number of agent groups. If not set, unlimited.
- conferences <number>: Limit the number of conferences. If not set, unlimited.
- colines <number>: Limit the number of CO-lines. If not set, unlimited.
- trunks <number>: Limit the number of trunks. If not set, unlimited.
- soap <bool>: Specify if SOAP is allowed (default false).
- barge <bool>: Specify if call barge in/teach in/listening is allowed (default false).
- secure <bool>: Allow sips calls (default false).
- cdr <bool>: Allow sending of CDR via SOAP (default false).
- lowrate <bool>: Enable the use of the lowrate codec (default false).
- recording <bool>: Enable the use of the recording feature (default false).
- name <text>: A descripting name for this license. This name is shown in the status web page.
- expires <time>: The date in number of seconds from 1970.
The key contains a hash over the features and the private key of the PBX key generator for cryptographic security of the key. The key is based64-encoded for easier transportation during the licensing process.
Technically, all features can be controlled seperately. In most cases, licenses will be offered in a package that contains a predefined feature set.
Ports
The Ports page lets you control which networking resources the PBX utilizes to communicate with the outside IP world.
When specifying ports, you can list the ports that you may bind to. You may either just specify a port number or you may explicitly specify the IP address and the port (separated by a colon, for example "192.168.1.2:8080"). If you are binding to IPv6 addresses, you must put a square bracket around the IP address (e.g. "[2001:db8::4]:5060"). If you are only specifying the port number, the PBX will bind to all IPv4 and IPv6 addresses on the system. If you want to bind only to IPv4 sockets, use the form "0.0.0.0:5060", if you want to bind only to IPv6 sockets, you can use "[::]:5060". In general, you may bind to more than one socket. The addresses must be separated by spaces. If you don’t want to use the service, leave the field empty. If you change a port binding, you need to restart the PBX service.
HTTP Ports
The http and https ports are used for the communication between the build-in web server and the web browser. The http port is used for insecure, but lightweight communication; the https port is used for secure, but a little bit more expensive communication.
By default, the http port is 80, the https port is 443. If you are running another service on your host or you want to gain some additional security, you may change these ports to any other available port.
If you cannot reach the system on any port, please use the netstat command to locate the ports that have been allocated by the system (see the operating system documentation how to use this program). If it all does not help, you must either reinstall the system or change the settings ip_http_port and ip_https_port in the Global Configuration File.
HTTP Port The default HTTP port is 80
HTTPS port The default HTTPS port is 443.
SIP Ports
In this section you can provide port information for the SIP protocol. SIP can run on UDP, TCP (or TLS). The SIP ports are used for insecure and secure SIP communication. By default, the system chooses port 5060 for sip and 5061 for sips. The PBX opens a UDP port and a TCP server port for the insecure communication and a TCP port for the secure communication.
If you are to set your DNS records up, you should set three records (assuming that you are operating the domain "test.com"):
- _sip._udp.test.com must point to SIP UDP port
- _sip._tcp.test.com must point to the SIP TCP port
- _sips._tcp.test.com must point to the SIP TLS port (TCP)
You can repeat the setup for every domain that you want to operate on the system.
SIP UDP Ports: If you are using SIP over UDP, then you need to set this field. The default port for UDP is 5060.
SIP TCP Ports: If you are using SIP over TCP, then toy need to set this field. The default port for TCP is 5060.
SIP TLS Ports: If you are using SIP over TLS(Transport Layer Security - Security over TCP), then you need to set this field. The default port for TLS is 5061.
SIP IP Replacement List: The is used when the PBX is used in a DMZ zone with NAT (see Office with private and public IP addresses). The setting contains a list of local IP addresses and their replacements. This list is used when the PBX sends out a SIP packet. Whenever PBX finds a local address in the list, PBX will replace the local address with the remote address. This way, SIP messages from the PBX will look like they have been sent from the replaced IP address. The format of the list is LAdr/RAdr [LAdr/RAdr]... Both the LAdr and the RAdr must be an IPv4 or IPv6 address (e.g. 192.168.1.2/203.4.5.12), DNS addresses are not being resolved here.
IP Routing List: THis field is used to override the operating system IP routing table. This setting "shadows" the operating system routing table, that means PBX will consult this setting before consulting/using the operating system. Whenever the PBX wants to find out what IP address is being used when sending a SIP packet out, it steps through the list and looks for a match (using the netmask Mask) to a destination address (DAdr). If there is a match, it will use the provided IP address (LAdr). See Office with private and public IP addresses for more information. The format of the list is DAdr/Mask/LAdr [DAdr/Mask/LAdr]... Both the DAdr and the LAdr must be an IPv4 or IPv6 address (e.g. 192.168.1.2), DNS addresses are not being resolved here. The mask must be in the form of an IP address, e.g. 255.255.0.0.
Couple of real examples and a basic network diagram here Image:Needhelp.gif
RTP
The RTP ports are used for sending and receiving media. You must specify a reasonable port range so that you have enough ports for all open calls. A port range of 100 ports is not unusual.
Most user agents send RTP media data from the same port where they expect to receive data. This is useful when a user agent sends media from behind NAT. The PBX can use this mechanism to establish a two way media path, even if the user agent is not able to determine its public IP address for media and is behind NAT.
Port Range Start: This is the starting RTP port that PBX will use for the media sessions
Port Range End: This is the end RTP port that the PBX will use for the media sessions.
Follow RTP: Some user agents use different ports for sending and receiving. Although they will not be able to operate behind NAT, they are within the scope of the IETF standards. To be able to be compatible with these devices, the PBX has flag called "Follow RTP". By default, this flag is set to "on". If you have trouble with devices that use different ports for sending and receiving, try to turn this flag off. Please note that some of the troublesome devices also have a flag to turn the usage of different ports off.
Please note that you can control this behavior also on trunk level. If only a specific trunk has this problem, you should use this setting only on the trunk level.
Codec Preference: This field lets you select what codecs will be supported on the PBX. The left selection box shows the allowed codecs on the PBX. If you do not want to use a specific codec, click on it and then click "Remove". This will move the codec to the right side selection box and it will not be used for any of the calls. We recommend to prefer high-quality codecs like ulaw (0), alaw(8), G.722 (9), G.726 (2) or GSM 6.10 FullRate (3). You can change the codecs without restarting the service.
Lock codec during conversation: In certain cases, PBX can switch to a common codec(advertised by both the end devices) to avoid the transcoding during the call setup. Even though this is legal from the protocol's point of view, many devices still cannot change codecs in the middle. To avoid this problem, you have to set "Lock codec..." to "on". If this is set, PBX will not switch the codec in the during call setup. This may introduce transcoding, which is a CPU intensive job. Default is off.
Packet length (in ms): This is the ptime parameter in the SDP. Default is 20 ms.
Multicast IP-Addresses:
Bind to specific IP address (IPv4):
Bind to specific IP address (IPv6):
Need to provide explanations for the above 3 fields Image:Needhelp.gif
SNMP
This section defines SNMP related settings.
SNMP Port: The SNMP port setting defines on which port the PBX will listen for SNMP requests. By default, this port is on port 161.
SNMP trusted addresses: This field lists the IP addresses that may send SNMP requests. If this setting is empty, the PBX will not accept any SNMP requests. Whenever a request is being rejected, the PBX writes a log message.
SNMP Community: An SNMP community is the group that devices and management stations running SNMP belong to. If you like to change the Community, you can do that from the web interface. It does not require a restart of the service. SNMP default communities are private (write), public(read). PBX, by default, is set to 'public'
For more details, see SNMP.
TFTP
The TFTP ports are used for provisioning purposes. Many SIP devices use tftp for automatic configuration. See File Access for more information on how the PBX may provide files for phones and other devices. See Automatic Provisioning for more details on how the provisioning works in detail.
TFTP Port: The TFTP port is on port 69 by default.
Allow TFTP Write: Some devices write log files using tftp. You may enable this with the "Allow TFTP Write" flag. Please notice that this feature makes it possible that users may write files that affect other devices and this may introduce system instability and security concerns. We recommend using this feature only for troubleshooting, if necessary. The uploaded file can also be seen in the log file.
NTP Port: PBX can act as a NTP server for the network. If you want to run the NTP server on the PBX, please provide a port number to run on, in this field.
Logging
When you install the system, you want to see how it works and how the PBX interprets the input to the system. Logging is a powerful mechanism to track the activity of the system.
For this purpose, the PBX keeps a list of log messages in memory and if you enter a filename it writes a copy of the log messages to the file system.
General Logging
Log Level (0-9): This field determines which log messages are put into the log. The range is between 0 and 9. If you select level 0 you will see only the most important messages, if you select level 9 you will see all available log messages of the system. Please note that choosing log level 9 creates additional load for the system and may create huge log files.
Log Length: This is the length of the internal log message buffer. This buffer is used to show the log messages in the web interface (see below).
Log Filename: The system ca write the log messages to the filename which you provide. If you put a dollar sign into the log filename, the system will replace the dollar sign with the current day. This will make sure that the log files don't get too big over time. Please don't forget to delete old log files from time to time, so that your file system does not get overloaded with too much logging information. Ex: The setting "log-$.txt" will create a log file under the pbx working directory with the name "log-yyyy-mm-dd.txt", where 'yyyy' is the year, 'mm' is the month and 'dd' is the date.
 |
Please notice that using a log file without a dollar sign in it is a ticking time bomb. The system will be rúnning fine, however as the disk space gets less and less you are running into trouble. After we few weeks of successful operation your system suddenly becomes instable and you will have a hard time finding out why. If you are using a dollar sign the PBX chooses a different file name every day, and in version 3 it automatically deletes old log file from the hard disk. Therefore, we strongly recommend to include a dollar sign in the log file name or don't log to a file at all. |
One of the first log messages that you will see is the working directory. If the Log Filename does not contain a path, the system will write the log file into that directory. You can specify the directory during the installation process.
Warning! Don't forget to lower the log level once the system is running. Especially when you write the log messages into a file, you will sooner or later get a hard disk full error, which a quite severe situation because the PBX will then not be able to save runtime data.
Specific Events
You can enable or disable logging on a subsystem level. The following subsystems are available:
Log general events: These events are of general interest, for example information about the working directory.
Log SIP events: Events in this module relate to the SIP traffic of the PBX.
Log media events: The PBX reports events about media processing, for example a one-way audio RTP timeout.
Log IVR events: This module logs events about processing user input, for example in the auto attendant or the mailbox.
Log email events: If you want to troubleshoot the email server interaction, you should turn this module on.
Log http events: This flag controls if events in the internal http server should be logged.
Log registration events: When a device registers or deregisters, it appears in this module.
Log SNMP events: SNMP events occur when a external SNMP agent requests information from the PBX.
Log trunk events: Log events that are related to the trunks, for example when a trunk registers the first time.
Log SOAP events: This subsystem deals with SOAP input and output.
Log TFTP events: In this module you will find events that have to do with the built-in tftp server and plug and play-related information.
Analyze audio levels: This feature measures the audio levels on a call leg. The volume is measured in dB (Decibel) relative to the maximum volume (0 dB would be maximum loudness). See Gain Adjustment for more information on this topic.
SIP Logging
When the PBX receives or sends a SIP packet, it determines if the packet will be logged and which log level this event will have.
Log REGISTER: REGISTER packets deal with the registration of extensions or trunks. If you are not interested in the registration traffic, set this setting to "off".
Log SUBSCRIBE/NOTIFY: SUBSCRIBE/NOTIFY deals with message waiting indications and LED state and other used subscriptions.
Log OPTIONS: OPTIONS are sometimes used to keep the SIP connection alive. In this case you will see a lot of those requests.
Log Other Messages (e.g. INVITE): All other packets usually belong to an ongoing call (e.g. INVITE, CANCEL, ACK, BYE).
When you enable the logging in one of the categories above, those SIP packets are logged on log level 7. If you log level is below 7, then the packets don't show up in your log.
Log Watch List (IP): The watch list filters the SIP packets by it's IP address. This feature is useful when you have a specific device that you want to watch in the PBX's log. You can list the IP addresses you are interested in the "Watch List (IP)" field.
Log Watch List: Defines the log level for the "Log Watch List (IP)". The log level for the watch list is independent from the log level of the packet which are not on the list (which are on level 7). That makes is possible to lower the log level and show the SIP packets of a specific device also on a lower log level.
Ex: If you want to log the SIP messages from 192.168.1.113 only, then set this IP address under "Log Watch List(IP)", set the "Log watch list" to 7, set the "Log Level" to 7 under the "General Logging" section, set the "Log SIP events" under "Specific Events" section. Turn off everything under "SIP Logging"
How to get the SIP logging
The most common logging that is generally asked for is the SIP log. The below section will provide some information on how to do that.
Open Admin->Settings->Logging
- Log Level - 7
- Log Length - say 300
- Log general events, Log SIP events, Log trunk events, Log Other Messages (e.g. INVITE) to "Yes"
- Save.
- Go to Admin->Status->Logfile, press 'clear'. This will clear the page.
- Make the call.
- Go to Admin->Status->Logfile, press 'reload'
Configuration
In this section you will learn how to save and restore system configuration, loading the configuration xml files on the fly.
| |
If you just want to back up your configuration on PC-based systems where you have access to the file system, you better just TAR or ZIP the working directory of the PBX. This will generate a complete backup of your system, including all temporary files, recordings, TFTP server files and so forth. The backup from the web interface is primarily for systems that don't provide access to the file system, such as the CS410 appliance and does not include files from the TFTP directory. Consider physically moving the backup to another storage place. You can even schedule this task every night, so that you automatically have a fresh backup for desaster recovery. |
Save/Restore Configuration
Making the backup
For the systems that do not have an easy access to the file system (say, CS410), PBX offers a backup and restore mechanism through the web interface. This feature is useful for other systems also, if the data to be backed up is less. otherwise you may put a very heavy load on the web server of the PBX, especially if you have many recordings in the file system. If you have a lot of data to be backed up, it is recommended that you use the OS specific tools to back up the data. Ex: On Windows, you can use tools like winzip. On Linux based systems, you can use 'tar'.
If you want to make a backup of the PBX configuration, you can use the "click here" link on the web page in the Save/Restore Configuration Section. When you click the link, you will be asked to save the file on the local computer. This backup will make a TAR backup of the whole configuration, including audio recordings. That means the file might get potentially large. Therefore you should perform this action in times when there is not too much going on on the system, this makes sure that you don't interfere with the service and it also makes sure that you get an integer snapshot of the system state.
The size of the file is limited by "Max. size of a configuration backup file" setting on the "Admin->Settings" page. If the TAR file exceeds the configured size, the backup fails. You will be returned with an empty file. Therefore you should check if the file size is okay after storing the backup; if there is a problem consider just making a file-system backup manually.
Restoring the backup
In order to restore a configuration, you must upload the file through the web interface. This might take a while; as with the saving of the configuration you should do this when there are no calls on the system. The restoring of the system will first erase your existing configuration, so be careful about this step.
File: Full path of the file to be restored. This file is basically the one you backed up in the previous section. Then click on "Save" to load the selected file. This will load the selected file and PBX will have the new configuration.
| |
On the same page you have a the "Factory Reset" button. If you press this button, instead of loading a file through the web interface the PBX will load a default configuration file from the file system into the PBX. All the data will be erased |
| |
We have introduced a new global variable -"max_tcp_length" - to accommodate the large tar files. You need to set this before you run the backup/restore (On how to set the global variable, please refer http://wiki.pbxnsip.com/index.php/Global_Configuration_File). Currently, this value is in bytes. So you will have to provide a value something like 384000000 (for 384MB). |
Request Configuration
If you have a web service that generates configurations on the fly, you can request the pull-down of a configuration from the web server. The PBX will initiate the web request on its own. This feature is useful in large-scale installations (many systems running as CPE devices) and you have a central configuration management database.
URL: Need to provide an example here Image:Needhelp.gif
Reload Configuration Files
There are certain configuration files that are loaded only during the startup phase. If you want to change them while the system is running, you can re-load them in this section.
ringtones.xml: This file is used to describe the available Alert-Info or Call-Info header that should be sent in the different alert-info headers. Since different phone vendors handle these headers differently, this file contains information about that.
pnp.xml: This file is used to describe what files are available for plug and play. Also, this file defines various parameters for different phone models and vendors.
Cerificate
Purpose
Certificates are used to indicate your communication partner that you are really the one that you claim to be. This is done using a third party that certifies your identity and issues you a certificate. The certificate comes for a domain name. Usually those certificates are used for web services; however the same certificates can also be used for SIP services.
By using a certificate you defend your installation against DNS redirection attacks. An attacker might get control over a DNS server (which you don't operate) and redirect all requests to his server. He then might be able to present the same certificate that you have, but he does not have the private key that you used when you requested the certificate from the trusted third party. Therefore, he will not be able to establish secure communication. This way the user agent can check if the host that he contacted is really the desired host and deny the connection if the public and the private keys do not match.
You can provide only one key to the PBX. That means for secure communication, you can operate only one domain in a secure way.
Format
The format of the certificate must be base64-encoded. You must include the private key and the certificate in the upload. Please note that uploading the private key this way might be intercepted by an intruder. You can minimize this risk by using the localhost address from the local machine.
In order to provide the key, just enter the ASCII string that you received from the trusted party, copy it into the text field and push the "Save" button. The PBX will then present this certificate to http and sip connection that require secure communications.
MoH (Music On Hold)
Purpose
"Music on Hold" (MOH) is used in several places. The name originally comes from the music that is played when an extension put a caller on hold to avoid silence in the line. For more information, see for example http://en.wikipedia.org/wiki/Music_on_hold.
The PBX uses MOH when a call in being put on hold and when a caller is waiting in an agent group. You can create several sources for music on hold; these sources can be used in parallel and can be used in different locations. Because these sources are system-wide available, they are part of the administrator settings. The music on hold can be selected on domain level. See the domain mode for more information.
There are 3 types of music on hold sources you can create on the PBX.
Files
The PBX can use one or more files for MOH. These files are read by the PBX on demand and played in an endless loop mode.
Name: Name of the source. You can provide any suitable name you like.
Type: Type of the source. In this case it is 'File'
Domain: You can assign the domain where this can be used. If you want this file MoH source available for all domains, you can select "All Domains"
Filename: This the name of the file to be played. This file must be in the "audio_moh" directory of the PBX (you must manually place the file there). The files must be in 8 kHz sampling frequency and they should be in 16 bit per sample signed format. The format must be mono WAV. You may also use other formats (u-law and GSM), but these formats will have less audio quality and require more CPU performance. The files are loaded only once. However, you should be careful, because long files will be read into memory; long files can easily take a lot of memory. As a rule of thumb, every minute of the file will take about one MB of memory space.
Wave Input
In Windows, the PBX supports additionally the reading from the audio input jack. This is a very convenient way to connect a CD, MP3 player or a radio to the PBX. The disadvantage of this method is that you can have only one external music source.
You can also internally loop the audio output of the local computer back to the audio input of the computer. With this trick, you can use any MP3 player running locally to provide a large number of MP3 files. However, we recommend keeping an eye on the memory usage of the MP3 player, as some players have memory leaks and slowly consume the memory of the computer.
Please note that this feature is currently only available for Microsoft Windows-based operating system. The appliance uses the RTP streaming mode for the audio input jack.
Name: Name of the source. You can provide any suitable name you like.
Type: Type of the source. In this case it is 'Wave Input'.
Domain: You can assign the domain where this can be used. If you want this wave input MoH source available for all domains, you can select "All Domains"
RTP Stream
Streaming RTP data becomes a popular way of providing music from external sources. Just like with a telephone conversation, the PBX receives the audio data in a standard RTP stream. There are several external tools available that are able to generate a compliant RTP stream. Because the PBX can have several RTP streams, you can use this method to generate different music on hold sources for the system.
The RTP stream must use G.711 encoding. There is no SIP signalling involved in this method and the PBX does not send any RTP data back.
Name: Name of the source. You can provide any suitable name you like.
Type: Type of the source. In this case it is 'RTP Stream'
Domain: You can assign the domain where this can be used. If you want this RTP stream MoH source available for all domains, you can select "All Domains"
Port Number: You must specify on which port the PBX should listen for RTP input (for example, "42000"). This port must be available on the system. If you change the setting, you might need to restart the PBX service, so that the change takes effect.
Editing MoH Sources
If you want to change a setting, you can just click on one of the links shown above the form. The PBX then will fill out the fields with the settings for the respective source. After making changes, you need to press the "Save" button. If you want to delete the source, click on the delete button. If you want to create a new source, you can use the clear button.
PnP (Plug and Play)
This whole section needs help Image:Needhelp.gif
Types of Plug and Play
MAC address based
In the method we use phone's MAC address for PnP. Note: Explain how to configure 1 device, multiple devices, 1 device under multiple extensions, multiple extensions under 1 extension, restrictions etc
HTTP based
Note: Inside the LAN and outside the LAN. Explain how to set/use the web password on the PBX, phone etc
Access
Motivation
There are several reasons why a system administrator might want to define who has access to the PBX:
- Protection against denial of service attacks. If you are operating the PBX on publicly available addresses, there is always the risk that someone tries to interrupt the service. Although the PBX has several protections against such attacks, it might be easier to rule such attacks out right from the beginning.
- Limiting the service to authorized addresses. You might also want to limit the service only to specific IP addresses. For example, while you might allow users to register their IP phones in the office, you might allow only selected users with their associated IP addresses to register their phones from home.
The motivation for the list is to provide the firewall type of functionality within the PBX application to reduce the chance of unauthorized access to the PBX.
The access control is not only limited to SIP. It also applies to all other protocols on the system, including HTTP, TFTP, SNMP and the other protocols used on the system. When the PBX acts as a client (for example, when performing DNS requests), the rules do not apply.
How it works
When a packet reaches the PBX, it will check the list of enabled and disables addresses for a match. If the result is that the request is ignored, then the PBX will just discard this packet without answer.
The PBX checks a list for matches. A match occurs if a 'source address' matches a 'check address' with the mask. More specific addresses are checked first; this makes it possible to define exceptions to the general rule. Also, the PBX checks IPv4 and IPv6 addresses separately.
If there is a match, the PBX checks for the type. If the type is "Allow" then the PBX accepts the packet. If the type is "Block" then the PBX blocks that request. If there is no match in the list, then the request is accepted.
If the list is empty, the access control is disabled. This is the default behavior after the installation of the product.
For UDP-based requests this is relatively easy. The request is just not answered. However, because the UDP port is open, there is no ICMP request sent to the origin. That means, someone who wants to attack the system might be able to figure out that there is an open port. But, since the PBX just discards these messages, the damage is limited.
For TCP ports, the situation is more complicated. In Linux, there is no way for an application to find out where a TCP connection is coming from until the connection is accepted. That is why the PBX first accepts the connection and then examines if the connection was allowed or not. If the connection was not allowed, then it is turned down immediately. In Windows, there is a special system call that first checks where the connection is coming from. If the source is not enabled, then the PBX does not accept the connection. However, the operating system already did answer the TCP connection request with an acknowledge, so that also in Windows there will be obvious that there is a application running on the ports.
The behavior is to a certain extent similar to a firewall. However, especially for TCP, a firewall will be able to keep the traffic completely out; someone testing the system out will not get any response back for a TCP request if the source IP address is not listed.
Configuration
In order to add a match entry, you can use the form at the bottom of the page. Just enter the IP address together with the net mask and the access type and hit the "Create" button. You should enter only as much information as needed by the net mask, for example "192.168.0.0" if the net mask is "255.255.0.0".
In order to delete an entry, just click on the delete button.
Changing the entry does not require a restart of the system. The changes take effect immediately.
Example
In this example, you want to give everyone in the LAN access, but rule out access from the public Internet, except for two employees working from home and for a trunk that comes from a service provider with a small range of IP addresses.
First entry: Address "127.0.0.1", net mask "255.255.255.255", type "Allow". This will make sure that you can always access the HTTP interface from the local computer.
Next entry: Address "192.168.0.0", net mask "255.255.0.0", type "Allow". This will make sure that everyone in the LAN can access the PBX.
Next entry: Address "0.0.0.0", net mask "0.0.0.0", type "Block". This entry will disable all packets by default (enter this as last, otherwise you will not be able to access the system any more).
Next entry: Address "213.1.2.3", net mask "255.255.255.255", type "Allow". This will give the remote worker access the PBX. Repeat the same entry for other IP addresses.
Next entry: Address "12.23.34.45", net mask "255.255.255.248", type "Allow". This entry is intended for the IP addresses of the ITSP.
Failover
Purpose and Scope
In many environments, the availability of the PBX service is critical for business. This page explains how to achieve failover support that restores the SIP service in a case of failure without manual intervention.
There are many ways to implement failover. For example, failover can be implemented using external tools like "heartbeat". In this case, the PBX acts like as a service like a web server that needs to be started up when the primary server becomes unavailable.
This page describes how to set up failover using standard Linux tools. It should be possible to use the setup also for other operating systems like FreeBSD. However Windows requires a different approach, which is not covered on this page.
Failover Behavior
The failover requires two servers running at the same time. The two servers are acting in active/standby operation. One server is active; the other one is checking the availability of the active server. As soon as the active server fails to answer the requests from the standby server, the standby server will load its configuration and then start operation. After the failed server restarts, it will run in standby mode until the then-master will fail.
During the failover, active calls get lost and registrations break. Depending on the speed of the failover process, the service can be restored in about a minute. Because the PBX keeps the registration intervals short, the phones will re-register within a short time and service may continue. However calls get lost and users have to re-dial the previous number. The lost calls are not billed.
Depending on the synchronization, other stateful information such as mailbox messages may also get lost. For example, if the file system is synchronized every minute, then mailbox messages left up to a minute ago may get lost.
In order to keep the IP setup simple, we suggest using one virtual IP address that acts as the IP address of the server pair. The active server has this IP address configured as its primary IP address. This keeps the routing table simple; which is very important for proper SIP service.
Setup
In order to have a backup, there must be two processes running that perform a supervision of the servers. If it should be necessary to set up firewall rules, then the two servers must be able to send messages through SIP. We use "PING" messages to check if the other server is still available.
IP Setup
The IP setup uses three IP addresses:
- The IP address of the two servers. Typically these addresses will be public IP addresses.
- A "virtual" IP address which is being used by the active server.
All three IP addresses must be in the same subnet.
DNS Setup
We recommend using DNS names to identify the service. This makes it easier to move domains or the whole server to a different location. There is a global flag called "provision_domain_name" which makes it possible to provision the DNS name of the domain instead of the IP address of the system (if set to "true").
DNS SRV is not required. It is only useful to make it easier to differentiate between HTTP and SIP services (_sips._tcp.domain.com for the SIP service and domain.com for the HTTP service). However it is also reasonable to use explicit names such like sip.domain.com for the SIP service and pbx.domain.com for the HTTP interface).
File System
Both servers must share the same files. Usually this can be achieved by using a network-mapped file system such as NFS or SAN. Running two file systems on both servers and having a automatic replication software is fine.
Periodically copying data between the servers is usually not a good idea. In the case that a server comes up after a failure, it will likely overwrite the active configuration with the configuration before the failover. However, you can use a shell script and use rsync to synchronize the changed between the servers. The script can check if the system is using the virtual IP address in order to find out if it should synchronize the data or not.
Installation
The installation of the failover case is similar to the installation of the single server installation. It is important that the PBX service gets automatically started after a reboot of the system. It also must be made sure that the two servers are using the same file system (see above).
We recommend consulting pbxnsip if you want to setup a failover solution.
Licensing
On MAC-based licenses, it must be made sure that the license key contains the MAC addresses of both servers. Because the two servers share the same setup and the same pnp.xml file, running the failover scenario with two different licenses.
