BeeSIP General Installation and Configuration¶
READ FIRST - Known Issues¶
There are several issues you might need to know before you use Beesip.
VMware ESXi¶
Running Beesip on VMware ESXi 5.1 and older may cause host to fail with a purple diagnostic screen.
To work around this issue, connect to each host in your environment using SSH and run this command:
esxcli system settings advanced set -o /BufferCache/MinZeroCopyBufferLength -i 512
To verify that the setting has been updated, run this command:
esxcli system settings advanced list --option /BufferCache/MinZeroCopyBufferLength
See also [[VMware knowledge base #2038767 http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2038767]]
Beesip sysupgrade¶
On x86 targets sysupgrade does not work correctly. If sysupgrade is initialized, on reboot it does not start with previous configuration as before.
To work around this issue, please wait until the device is fully booted after sysupgrade and then reboot it one more time.
Installation guide¶
Common x86 PC¶
The easiest method to install BESIP image is to boot up any Linux based distribution and download BESIP image provided from [[http://mirror.opf.slu.cz/besip/1.2beta3/owrt_trunk/x86/]]. This repository consists of targets which some of them provides images for common device and also virtual drives for virtualization (as a vmdk files).
If your Linux/MacOS/... (that has dd) machine is already booted up, the BESIP image should be installed this way (We presume that you need to be root to install BESIP image.):
But be afraid!! It will erase entire disk!
dd if=beesip-virtual_1.2beta3-owrt_trunk_rxxxxx.img of=/dev/Xda
Where variable X depends on your type of your harddrive (SATA or IDE).
Virtualized host using KVM¶
This command will run kvm, redirect serial console to tty, redirects ports to access SSH via localhost:2222 and emulates network card e1000.
kvm -net nic,model=e1000 -net user,hostfwd=tcp::2222-:22 \
-nographic \
-drive file=beesip-virtual_1.2beta3-owrt_trunk_rxxxxx.vmdk,index=0,media=disk,if=ide
NOTE: if you do want to install Beesip image onto device which is not built by our targets, please follow instructions how to built your custom Beesip image for your specific target in section OpenWrt
VMware Player, Workstation or ESXi¶
Please, download the vmx and vmdk files:
http://mirror.opf.slu.cz/besip/1.2beta4/owrt_attitude_adjustment/x86/
And just run the beesip-virtual_1.2beta4-owrt_attitude_adjustment.vmx file to run virtual machine with Beesip.
VirtualBox¶
You can follow the instructions for VMware, or you can follow this guideline - [[http://wiki.openwrt.org/doc/howto/virtualbox]] that shows how to install OpenWrt image. Those steps are the same for BESIP image. Just create new virtual machine with existing virtual hard drive, enable at least one console port and bridge network card.
Any OpenWrt enabled router/device¶
Methods how to install to OpenWrt enabled device (like as wifi routers) are described here - [[http://wiki.openwrt.org/doc/howto/generic.flashing]].
Usage guide¶
First boot¶
On first boot there is an init script which prepares OpenWrt to BEESIP default state. It prepares the whole BEESIP configuration and the configuration for BEESIP associated applications. After BEESIP is prepared, the .besip-prepared stamp is created in the root directory.
You can verify the preparation procedure by running following command:
beesip isprepared
If you get message "Beesip is ready to use" after issuing command "beesip isprepared", then Beesip is prepared and you can start configuring it. It is recommended to reboot the machine after the first boot.
First usage and initial configuration (x86 variant)¶
If your image is succesfully prepared to use, it is recommended to set your root password, which will be shared among all services, e.g. your system password, your password to administration interface, to asterisk web interface and to monitoring interface.
You can set/change your password by:
passwd root
Until then your system will accessible only via telnet. After issuing command "passwd" for root user SSH protocol is used for remote configuration.
Beesip is based on OpenWrt, so all system configuration remains the same as for OpenWrt. For the first configuration it is recommended to configure your network interfaces in file /etc/config/network.
For static IPv4 configuration there is an example configuration:
config interface 'eth0'
option ifname 'eth0'
option proto 'static'
option ipaddr 'yourIP'
option netmask 'yourNetmask'
option dns 'yourDNS'
option gateway 'yourNetworkGateway'
For dynamic IPv4 configuration:
config interface 'eth0'
option ifname 'eth0'
option proto 'dhcp'
Beesip helper script¶
There is an application (just run beesip in command line) which simplifies several OpenWrt procedures and prepares OpenWrt to debug or to use.
Factory defaults¶
On squashfs filesystem variants of Besip
beesip fd
or
beesip factory-defaults
has to be called if you want to restore system to initial state.
Crash reporting¶
beesip cr start
beesip crash-reporting collect
This command controls crash-reporting system. If collect parameter is called, it creates an archive of overlay, collected logs and overlay to be used for debugging in /root/ directory.
Security module¶
beesip security start
beesip security stop
Those commands starts or stops Besip security module. More info for security module below in section Besip Security.
System upgrade¶
beesip system-upgrade besip-image.img
This command upgrades system with provided firmware image.
Importing gateways from IPtelix to Besip¶
This command imports VoIP gateways from IPtelix into SIP engine specified in /etc/config/besip. Optionally you can run it with stdout parameter which only prints requested data to stdout.
Example configuration specifies which engine is used and for which engine are routing data imported. It also specifies where to obtain configuration from. See below:
config beesip gateways
option import_for_engine 'ast11'
option import_uri 'https://iptelix.cesnet.cz'
option country_code 'XXX'
option prefix 'YYYYY'
Supported engines are now ast11 for asterisk 11.x and below.
The specified URI providing information about SIP gateways is replacable. The URI should have gateway trunks and its extensions located at following postfixes for any URI:
/export/asterisk/11/sip.conf /export/asterisk/11/extensions.conf
You can import SIP gateways by issuing command:
beesip import-gateways
When SIP routing information is imported, you can also setup your dialplan by setting up prefix and country_code variables. When it is done, you can generate your new extensions.conf by issuing command:
beesip setup-dialplan
UCI provisioning for OpenWrt¶
UCI provisioning system is tool for OpenWrt distribution, which will allow OpenWrt box to be automaticaly configured via network. There are several ways and methods how to discover what to provision. Uciprov is modular, shell based provisioning which can be easily expanded. Most common usage is to download UCI configuration to the box just after factory defaults. But there are much more ways how to use Uciprov.
How it works¶
Uciprov has three ways how to be run. First is simple from init script, second is based on interface state change and third is regular interval check. Uciprov default options can be overwritten during provision, so second stage provision will be based on new parameters. This is common way how to provision more kind of devices based on IP range, DHCP or box type.
Basic run procedure¶
When uciprov is started (from init or from DHCP client process), it will collect all informations from uciprov config, tries to resolve all macros and get all possible uris. When uri is available, it is fetched. Fetched file is expected to be text input, which is in uci batch format. File can contain macros which will be resolved during provision. See above. For example:
set network.wan.hostname={hostname}
set network.lan.dns={dns}
set network.lan.dns_search={domain}
set network.wan.vendorid=Eduroam
set network.@switch[0]=switch
set network.@switch[0].name=switch0
set network.@switch[0].reset=1
set network.@switch[0].enable_vlan=0
set network.@switch_vlan[0]=switch_vlan
set network.@switch_vlan[0].device=switch0
set network.@switch_vlan[0].vlan=1
set network.@switch_vlan[0].vid=1
set network.@switch_vlan[0].ports="0 1 2 3 4"
Stages¶
Stage1 is used for fetching informations about available uris and macros. Stage2 is used to resolve uris and get informations from there.
Uciprov macros¶
Uciprov can use macros for stage 2. Some macros are directly in uciprov, but modules can set any macros. Default macros:
{hostname} # Hostname
{domain} # Domain from DHCP
{dns} # DNS server IP (first of list)
{fqdn} # Fqdn of host
{mac} # Mac address of provisioning interface (aa-bb-cc-dd-ee-ff)
{mac2} # Mac address of provisioning interface (aabbccddeeff)
{mac3} # Mac address of provisioning interface (aa:bb:cc:dd:ee:ff)
{ip} # IP address of provisioning interface
{fd} # Box in factory defaults (0/1)
{ifname} # Provisioning interface name (like eth0)
{oifname} # Owrt Provisioning interface name (like wan)
{sr} # Revision of fistribution (like git rev)
{cn} # Codename of distribution (like barrier_breaker)
{rl} # Release of distribution (like 14.07)
{tgt} # Distribution target and subtarget (like x86_64/generic)
{cpu} # CPU (like x86_64)
{sub} # Subtarget
{board} # For some boxes, this is board identification string. Like tplink-wdr3600-v1. This can be used to fetch right image for box
{ovr} # Overlay mounted (0/1)
{nettime} # Network time obtained (0/1)
{uci_uris} # All uciprov uris
{uri_static1} # static uri 1
{uri_static2} # static uri 2
{uri_static3} # static uri 3
{dhcp_uri} # Uri fetched from DHCP server
{m} # Module which performs given action (eg. uci for uciprov, tgz for tgz module)
Uciprov parameters¶
There are lot of parameters which affect how Uciprov works. It is important to know that basic parameters are EMBEDDED into image so changing them afterward has no effect for factory-defaults boxes. It is important to setup good configuration to fit your needs. Uciprov defaults can be changed using standard openwrt config procedure.
Global UCI parameters¶
# Enable uciprov at all. If set to zero, uciprov will do nothing.
option enable '1'
# When box is in factory defaults (first run of uciprov after factory reset), This option is 1
# After first run, this is automaticaly set to 0
option factorydefault '1'
# Set of protocols to fetch informations from separated by spaces
# Order of protocols cannot be changed here. There are hardcoded into scripts.
# It is possible to turn on or off
option uri_retrieval_protocols "dnssec dns dhcp static"
# Urls to fetch data from. There are more urls, which can be global or device specific.
# They are evaulated in order 1,2,3. All defined url will be tested.
# You can use macros inside urls. Use 'uciprov' command without parameters to see all macros.
# {hostname} 'somehost' Hostname from DHCP or static config
# {domain} 'some.doma.in' Domain
# {mac} 'so-me-ma-ca-dd-rr' Mac addr
# {ip} 'x.x.x.x' IP of wan
# {fd} '1' This will be 1 or 0 according to 'factorydefault' option
# This url will be expanded to http://beesip/uci-1 in first-time run and http://beesip/uci-0 in other cases
# Because uri does not contain device specific macros, it will be applied to all boxes!
# For uci provisioning, module name is uci
option uri_static1 http://beesip/{m}-{fd}
# Example to feed more macros into php script
# option uri_static1 "http://server/script.php?mac={mac}&board={board}&fd={fd}&module={m}"
# This settings will be applied to group of boxes with same CPU. Like uci-x86 for UCI , tgz-x86 for tgz module
h2. option uri_static2 http://beesip/{m}-{cpu}
# This is box specific settings, regardless of factorydefaults. Will be fetched and applied any time.
option uri_static3 http://beesip/{mac}/uci
# prefix which is searched when using DNS provisioning
option dns_prefix "beesip"
# Interface which is used for provisioning. In most cases, wan
option interface "wan"
# If set to 1, box is rebooted after provisioning. Be carefull for endless booting!
option reboot_after_cfg_apply 0
# In some cases, it can take a while to initialize /overlay. If this is set to number, uciprov will wait maximum this number of seconds until /overlay is mounted in background
option wait_for_overlay 120
# Before rebooting, it is possible to wait this number of seconds (to be able to recover some endless loop)
option reboot_delay 60
# If set 0 number bigger than 0, uciprov will repeat periodicaly to fetch config.
# This can be used to periodicaly fetch new config (in this example, each 120 seconds)
option repeat 120
# If set to 1, uciprov will continue in periodic uri fetching.
# When set to 0, uciprov will stop to fetch next uri after first successful provisioning data
option repeat_on_success 0
Protocol hooks for getting uris¶
Uciprov is modular and there can be more modules to fetch uris from. For example, it is possible to set "bootfile" parameter of DHCP to override UCI uris. There are three modules by default: STATIC, DHCP and DNS. Static is configured by uciprov config (uri_static1, uri_static2, uri_static3). DHCP is configured from bootfile parameter of DHCP. Next to this, it is possible to create TXT record. Uciprov will try to get TXT record "dns_prefix" and fetch uri from there. All uris are glued and after it, fetched.
Modules functions¶
Next to this, uciprov is able to do some more deployment than only UCI. Modules can hook to stage1 or stage2 hooks.
DHCP module¶
DHCP module is responsible for getting informations from DHCP server. This is not DHCP client but it uses DHCP client to ask for DHCP options.
DNS module¶
DNS module is responsible for getting informations from DNS server. It can use either DNS or DNSSEC protocol.
STATIC module¶
STATIC module is responsible for getting informations staticaly from uci config.
Common config for all modules¶
Every module will read basic configuration options from its container. Next to this, there can be module specific parameters.
config uciprov somemodule
# If module should be enabled at all.
option enable 1
# If it should apply any time or only in factory defaults
option only_on_fd 1
# Uri for module. If this parameter is missing, static or dhcp uris are used and module name is expanded by {m} macro.
option uri "http://somewhere/{cpu}/{board}/config"
# Version is used for any module to know if module was already applied. After successful module run, this option is changed to md5 sum of received data from its uri.
# If md5 of fetched file is same as this config option, module is skipped
option version 1.2.3
Sysupgrade module¶
Sysupgrade module is used to automaticaly upgrade boxes from common urls. It takes config from sysupgrade part of uciprov config:
config uciprov sysupgrade
option enable 1
option only_on_fd 1
option uri "http://beesip/images/{board}/su.img"
option version 0.2.4
This config instructs sysupgrade module to upgrade system only when box is in factory defaults state. When there is no limit on factory defaults, file uri will be fetched any time! After it, md5 is computed and compared with 'version' option. If it differs, it is sysupgraded.
config uciprov sysupgrade
option enable 1
option only_on_fd 1
option uri "http://beesip/images/{board}/su.img"
option version 0.2.4
Tgz module¶
Tgz module is created to deploy tgz files for configurations which do not support UCI. Works similar to sysupgrade. If there is uri available to fetch, it is fetched and untared in root.
config uciprov tgz
option enable 1
option only_on_fd 1
option uri "http://beesip/files/files.tgz"
# When to run module. {preinit|postinit|preapply|peruri}
# preinit. Module will be run one time just after stage1 when all uris are known
# postinit. Module will be run one time just after uci apply
# preapply. Module will be run one time just before uci apply
# peruri. Module will be run for each uri, discovered by stage1. Eg. three times for static1,static2,static3
option run_on "preinit"
option version 0.2.4
# If set to 1, there will be macro expansion enabled for fetched data.
option macroexpand 1
This files will be deployed to all boxes after factory defaults only.
Recovery module¶
This module works for box recovery if everything else fails. It will fetch given uri and read data from it. If data are same as flag, defined in config, emergency script is run. Emergency script could be for example stop firewall, restart telnet server or any other script. If DHCP is set to 1, UCI uris are fetched from DHCP "bootfile" too.
config uciprov recovery
option enable 1
option uri "http://beesip/fd/fd.flag"
option fd_flag "1234"
option dhcp 1
option script ""
SslDeploy module¶
This module deploys SSL key and certificate into box. Key will be generated directly in box. CSR request will be uploaded and certitficate will be downloaded after signing from remote server.
config uciprov ssldeploy
option enable 1
option algo rsa
option bits 2048
option subject CN={mac2}
option keyfile /etc/ssl/box.key
option crtfile /etc/ssl/box.crtfile
option csrfile /etc/ssl/box.csr
option keyowner root:root
option keychmod 700
option push_uri https://csrreq.host/post/{mac2}
option fetch_uri https://crtget.host/{mac2}
Services module¶
This module enable to disable/enable services during provision. It will fetch service control file (see above) and do what is needed there.
config uciprov services
option enable 1
option uri "http://beesip/services"
Service control file:
#service action [condaction] #action: start|stop|enable|disable #condaction: fileexists filename #will run this action only if filename exists #examples kamailio stop kamailio disable radsecproxy start fileexists /etc/radsecproxy.key
Opkg module¶
This module can automaticaly setup opkg repositories, update package info and install some packages automaticaly, during uciprov. If replace_repo is 1, system repositories will be cleared. In other way, package lists are added to list. There can be any number of packages to install/upgrade automaticaly.
config uciprov opkg
option enable 1
option uri "http://beesip/opkg"
Opkg control file:
remove_uri 'bb_base' add_uri src/gz bb_base http://downloads.openwrt.org/barrier_breaker/14.07/ar71xx/generic/packages/packages/ option http_proxy http://proxy:3128/ update install pkg1 pkg2 pkg3 .... remove pkg1 pkg2 pkg2 ...
Zabbix module¶
This module is for getting information about host from zabbix server. It can obtain uris and macros for stage1 and can get information for stage2. This module can be connected to zabbix_agentd package. Together with autoregistration/discovery, this is very strong tool. After boot, Zabbix uci configuration is obtained. Next to this, zabbix_agentd connects to zabbix server and tries to autoregister. Zabbix can be configured to run some actions after successful registration. If administrator wants precise control over process, host can be created even manualy in Zabbix and disable autoregistration. After registration, zabbix module is able to fetch informations about host from zabbix server and even send some data using Zabbix API.
config uciprov zabbix
option enable 0
option uri "http://zabbix/api_jsonrpc.php"
option apiuser "uciprov"
option apipw "uciprovpw"
Writing hooks¶
Uciprov is prepared to use hooks. Each hook is called at specified event. Module can hook to this event and do some work. It is enough to catch hook in module:
get_uri_dhcp(){
local duri
duri=$(get_dhcp_var $interface bootfile)
setmacro uci_uris "$duri"
setmacro dhcp_uri "$duri"
}
boot_hook_add uciprov_geturi get_uri_dhcp
Each time uciprov will try to get uciprov uri, it will call function get_uri_dhcp which will set macros uci_uris and dhcp_uri. These macros will be available later for expansion in uris.
Available hooks¶
uciprov_geturi¶
This hook is called at each stage1 of uciprov when needed to fetch uris for stage2.
uciprov_fetchuri¶
This hook is called for each fetching of uri. Uris format is protocol://uri . Module can be hooked to some protocol.
uciprov_testuri¶
This hook is called before each fetching of uri to test if it is reachable. If it is not defined, fetchuri is used.
uciprov_peruri¶
This hook is called per each uri discovered by stage1. Actual uri is parameter of function
uciprov_preinit¶
Called before rest of init script. Just after setting macros and uris from stage1
uciprov_preapply¶
Called before uci apply one time.
uciprov_postapply¶
When apply of at least one uri was successfull, this hook will be called.
Documentation for Beesip 1.0¶
Documentation: http://homel.vsb.cz/~voz29/files/besip_v1.0.pdf