Installation Manual for ViciBox v.8.1
http://www.vicibox.com/

Foreword

Some basic Linux skills and general IT knowledge is assumed throughout parts of this document. For this reason, this guide does not cover topics such as basic networking, CD burning, partitioning scheme design, varying infrastructure methodologies, validity of install, and other unmentioned topics or variations of installation. To find out more about any of the steps in this document, or to learn more about any particular ViciBox install or ViciDial setup, we suggest you search and ask questions on the ViciDial forums at http://www.vicidial.org/VICIDIALforum/. In addition, you can find more information with regards to Linux, OpenSuSE, and other general topics by using Google and/or the official OpenSuSE Leap v.42.3 documentation located at https://doc.opensuse.org/opensuse.html

ViciBox is a self-contained installation CD based upon the OpenSuSE v.42.3 Linux distribution. It includes both online as well as offline installation capabilities. It is packaged as a LiveCD that can be used as an installation medium, rescue disk, or hardware testing resource.

Paid Support is available through the ViciDial Group (www.vicidial.com) to help with any portion of a ViciBox or ViciDial installation. Custom development of both ViciBox and ViciDial are offered through the ViciDial Group as well.

Alternatively, if the prospect of installing and maintaining your own ViciBox/ViciDial installation seems too daunting, the ViciHost (www.vicihost.com) service is available to give you all the features and benefits of ViciDial without having to maintain physical servers or worry about installing and updating ViciBox

As of the writing of this document the current version of ViciBox is v.8.1.2. It is built with the following software and features :
•	OpenSuSE Leap v.42.3
•	Kernel v.4.4.155
•	Asterisk v.13.21.1-vici
•	DAHDI v.2.11.1
•	LibPRI v.1.6.0
•	Amfletec VoiceSync v.1.3.8
•	OpenR2 v.1.3.3 for MFC/R2 supporting
•	ViciDial SVN v.2.14-689a build 180922-0958 revision 3035
•	Automated G729/G723 codec installation with internet connectivity
•	Integrated firewall with VoIPbl.org and White/Dynamic/Black IP ACL
•	CertBot set-up script to generate valid LetsEncrypt.org SSL certificates
•	WebRTC ViciPhone ready
Hardware Recommendations and Dimensioning

The recommended minimum hardware specifications for ViciDial is as follows :
•	Quad-Core CPU 2.0+Ghz
•	4+ GB RAM
•	160+ GB RAID-1 Hard Drive setup

A ViciBox “Express” system consists of all major roles including Database, Web, and Telephony server. Using the minimum hardware specifications listed above, this would be well suited for a call center up to 15 agents doing outbound calling with call recordings at a 4:1 ratio. When used for inbound the same minimum hardware specifications are acceptable for up to 25 agents. Please note that the figures presented are a conservative guideline and that your actual system capacity is heavily determined by the number of agents, number of leads, concurrent call count, dialing ratio if applicable, campaign settings, and the general capacity of the hardware. It is for this reason that additional specifications were provided should you run into any minor load issues. Particular attention should be paid to the size of the hard-drive(s) installed in the system if you record your calls. The most frequent issue new customers experience is a crashed server due to the hard drive filling up with recordings.

Clustering is where multiple individual servers perform specific roles within ViciDial. Those roles are Database, Web, Telephony, and Archive server. Clustering should generally be used for an install consisting of more then 20 outbound agents or 30 inbound agents. If you do not know or are unsure of whether you should perform a clustered install please consult with the free community-based ViciDial forums or paid-for ViciDial Group for support. Please be prepared to explain your planned installation including number of agents, call type (Outbound/Blended/Inbound), expected dialing ratio or concurrent call volume, archival requirements, and any other unique processes or requirements you may have. This will help generate an accurate answer to your questions.

Clustering of the Web and Telephony roles in vicidial is done horizontally. This means that as your capacity grows you simply add more servers to your cluster to compensate. A cluster should always start with at least one dedicated Telephony server and a combination Database and Web server. If your total agent capacity will be less then 50 agents then you can use the optional server specifications provided under the “Compatibility and Prerequisite” section for your Database. All other clustering options should use one of the database-specific specifications listed under the “ViciBox Cluster” section. All Web and Telephony servers just need to adhere to the base specifications listed under the “Compatibility and Prerequisite” section.

In general, you can expect to get 25 outbound agents dialing 4:1 ratio or 50 inbound agents with 100 concurrent lines on a dedicated Telephony server using the standard hardware specification. It is recommended to use the optional specification for recording long call durations or inbound call centers.

A dedicated Web Server will handle approximately 150 agents using the standard hardware specification. When more then one web server is used it is recommended to configure a third machine to act as a load-balancer for the agent interface between the multiple web servers. The agent will initially go to the load balancer to log in and then be redirected to one of the back-end servers. Configuration of the load balancer is done through the use of the mod_proxy_balancer module in Apache and is not covered by this document. There are many examples and walk-throughs available by searching the internet. Alternatively, the ViciDial Group can install and set-up a load balancer for you through paid support options.
Phase 1 – OS Installation

 1.	Download the current ViciBox ISO from http://download.vicidial.com/iso/vicibox/server/
 2.	Burn ISO to CD/DVD or USB thumb drive and boot from it.
 3.	At the boot screen, select “ViciBox_v8_1” and press ENTER to boot the ViciBox live CD.
 4.	At the login prompt type in ‘root’ and press ENTER.
 5.	As the password prompt type in ‘vicidial’ and press ENTER.
 6.	To begin the OS installation type ‘os-install’ and press ENTER. If you wanted to do anything prior to OS installation you would do that before completing this step.
 7.	At the license screen press ALT-N to select ‘Next’ and move to the next screen.
 8.	To change the Region press ALT-E and use the up and down arrow keys to select the proper Region.
 9.	To change the Time Zone press ALT-Z and use the up and down arrow key to select the proper Region.
 10.	Verify that the selected Region and Time Zone are correct and press ALT-N to select ‘Next’ and move to the next screen. The Region and Time Zone should be set for the server’s physical location, not the location of the agents.
 11.	To accept the default partitioning scheme press ALT-N to proceed to  the next screen. By default the partitioning scheme assigns 4GB to swap and the rest to / (root). If there is a second drive, like an SSD, that is to be used solely for database access it would need to be mounted under /srv/mysql 
 12.	Type in the new root password and press the TAB key to move the cursor down to the Confirm Password field. The default root user password is ‘vicidial’. The TAB key can be pressed multiple times to cycle through the fields.
 13.	Re-type the password in the Confirm Password field to verify it. DO NOT LOSE OR FORGET THIS PASSWORD OR YOU WILL NOT BE ABLE TO LOG INTO THE SERVER’S OPERATING SYSTEM IN THE FUTURE.
 14.	Press ALT-N to select ‘Next’ and move to the next screen.
 15.	If the system determines that the entered root password is not a high security password it will prompt you to verify you want to use that password. Using the TAB key make sure ‘Yes’ is highlighted and then press the ENTER key to proceed to the next screen.
 16.	An installation summary screen will show you the configured install options. If there are no changes to be made to the installation options presented, press ALT-I to start the installation process. EVERYTHING AFTER THIS STEP WILL RESULT IN THE SERVER BEING FORMATTED AND ALL DATA ON IT BEING LOST.
 17.	To confirm the start of the installation process press ALT-I again. EVERYTHING AFTER THIS STEP WILL RESULT IN THE SERVER BEING FORMATTED AND ALL DATA ON IT BEING LOST.
 18.	When prompted, use the TAB key to select ‘Reboot Now’ and then press the ENTER key. The CD/DVD or USB thumb drive can be removed at this step.
 19.	After rebooting type ‘root’ at the login prompt and press the ENTER key.
 20.	At the password prompt type in the ‘root’ password from step 12 and press the ENTER key.

Upon successful login you should see a red prompt that says ‘vicibox81:~ # _’ with the underscore blinking. This is the ‘root’ prompt and where you should begin Phase 1.5 and Phase 2 installations. If you have other set-up tasks to do you can do those at this time. Phase 1.5 includes some recommended and optional set-up tasks that can be performed prior to the final Phase 2 installation of ViciDial.

Phase 1.5 – Recommended and Optional installation steps

Network Configuration – HIGHLY RECOMMENDED
 1.	If not already please login as the ‘root’ user to get to the root prompt. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 2.	Type ‘yast lan’ and press the ENTER key to start the network configuration. Optionally, you can type ‘yast’ and navigate to the network configuration by going to System → Network Settings.
 3.	Using the TAB key, press it until the network card is highlighted. If you have multiple network cards, use the up and down arrow keys to select the proper network card to configure.
 4.	Press ALT-I to edit the configuration of the selected network interface.
 5.	Press ALT-T to select ‘Statically assigned IP Address’. All servers in a ViciDial cluster should have a statically assigned IP.
 6.	Press ALT-I or the TAB key to move to the ‘IP Address’ field.
 7.	Enter the IP Address for this network interface. This IP is determined by your network environment and is beyond the scope of this installation guide.
 8.	Press ALT-S or the TAB key to move to the ‘Subnet Mask’ field.
 9.	Enter the Subnet Mask for your network environment. The subnet mask can be entered in either dotted notation (A.B.C.D) or CIDR notation (/XX).
 10.	Press ALT-G to view the General settings for this network interface.
 11.	Press ALT-X to change the Firewall Zone for this network interface.
 12.	Using the Up and Down Arrow keys, select the ‘Internal Zone’ for the network interface if it is not directly attached to the Internet or ‘External Zone’ if it is directly attached to the Internet. For example, if the IP address for this server is an RFC1918 private IP like 192.168.X.Y or 10.X.Y.Z then this should be considered an Internal Zone connection.
 13.	Press ALT-N to accept the configuration changes and return to the Network Settings screen. If you have multiple network interfaces to configure you can repeat steps 3 through 12 for each of the additional interfaces. Network configurations can be complex and consulting a qualified network technician is recommended if there is any doubt as to what settings to use.
 14.	Press ALT-S to configure the Hostname and DNS settings.
 15.	Press ALT-T or the TAB key to move to the ‘Hostname’ field.
 16.	Enter the unique Hostname for this server. All servers MUST have a unique 16-character or less hostname for a clustered installation to install properly. The recommended naming convention is to use DBX, WebX, and DialX where X represents the numerical sequence of that server. For example, the first Telephony server would be Dial1, the second Dial2, etc. The web servers would be web1, web2, etc. Please avoid arbitrary names like ‘Zeus’, ‘Batman’, ‘Lemonade’, etc.
 17.	Press ALT-D or the TAB key to move to the ‘Domain Name’ field.
 18.	Enter the Domain Name for this server. The domain name ‘vicibox.local’ can be used if a domain name is not known or not set-up in the current Network Environment.
 19.	Press ALT-1 or the TAB key to move to the ‘Name Server 1’ field.
 20.	Enter the primary DNS server for your network. This will typically be the IP address the router if you are using a private IP, or the DNS servers for your ISP if you are not. The ip ‘8.8.8.8’ can be used if the primary DNS server is not known or provided.
 21.	Press ALT-2 or the TAB key to move to the ‘Name Server 2’ field.
 22.	Enter the secondary DNS server for your network. This will typically be the DNS server from your ISP. The ip ‘4.2.2.1’ can be used if the primary DNS server is not known or provided.
 23.	Press ALT-U to change to the Routing screen.
 24.	Press ALT-F or the TAB key to change to the ‘Default IPv4 Gateway’.
 25.	Enter the Default Gateway for your network. This will typically be the router’s IP if the server is configured with a private IP address or the gateway as provided by the ISP if it’s directly attached to the network.
 26.	Press ALT-O to select ‘OK’ and save the network configuration. This will cause the network to reload and the changes to become active. It is possible during this step that the network will not reload cleanly. To prevent this issue from causing any problems it is recommended to reboot the server prior to the Phase 2 ViciDial installation.
 27.	Once back at the root prompt, type ‘ping -c6 google.com’ and verify that the server is properly able to ping out onto the internet.

In addition to basic network configuration, you can configure the built-in firewall by typing ‘yast firewall’. This interface will allow you to open ports and selectively allow access for certain IPs. This will not configure the ViciBox Firewall (VB-firewall.pl) but will allow static firewall entries.

Install Updates – RECOMMENDED AND REQUIRES INTERNET CONNECTIVITY
 1.	If not already please login as the ‘root’ user to get to the root prompt. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 2.	Type ‘zypper ref’ to refresh all installed repositories for the latest packages.
 3.	Type ‘zypper dup -y’ to install updated packages and any package changes. This step might take a while depending upon the age of the installed ViciBox image and the speed of your internet connection.
 4.	After the updates are done installing, type ‘reboot’ to reboot the server and load and newly updated software.

Switch to Asterisk v.11 – OPTIONAL BUT REQUIRED IF INSTALLED SVN IS UNDER 2960
 1.	If not already please login as the ‘root’ user to get to the root prompt. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 2.	Type ‘vicibox-ast11’ and press the ENTER key to begin the switch to Asterisk 11. This should ONLY be done prior to Phase 2 ViciDial installation. Doing this on a configured server will cause that server to no longer work properly with ViciDial.

Install LetEncrypt/Certbot SSL – OPTIONAL FOR WEB AND TELEPHONY SERVERS
 1.	If not already please login as the ‘root’ user to get to the root prompt. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 2.	Type ‘service apache2 start’ to start apache for the verification process.
 3.	Verify that your Fully Qualified Domain Name is properly pointing to this server by going to http://<FQDN> and seeing if you browser says “It Works!”.
 4.	Type ‘vicibox-certbot’ to start the simplified CertBot setup wizard.

The CertBot verification will only work if this server has a Fully Qualified Doman Name (FQDN) properly pointed to it. If your network environment is complex enough where a public FQDN cannot be mapped to your server publicly then it is recommended to use a conventional SSL provider.

Change ‘root’ user password – OPTIONAL (READ COMPLETELY FIRST)
 1.	If not already please login as the ‘root’ user to get to the root prompt. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 2.	Type ‘passwd’ at the root prompt.
 3.	Type in the new root password and then press the ENTER key
 4.	Verify the new root password by typing it in again and then pressing the ENTER key

DO NOT LOSE THIS PASSWORD! It is always needed for any sort of support (remote or otherwise) that needs to be done at the Operating System level. It is not trivial to recover a lost root password and requires someone to physically be at the server or using an IP-KVM during the recovery. It is recommended to chose a root password that is more of a phrase then a single word. Avoid choosing passwords that are overly complex, random, or hard to remember. Such passwords end up being written down on a piece of paper and shoved in a drawer or taped to the front of a server. An example of a pass phrase would be “ThisIsViciBox!”.

It is recommended to use 12 or more characters in your root password. None of the passwords used in this document should be used on a server that is directly connected or exposed to the internet. All alphanumeric characters (A through Z and 0 through 9) are valid in a root password along with the special characters @=/+-!~ 
Phase 2 – ViciDial Installation

There are two different types of ViciDial installations. The first one is an ‘Express’ install which is  primarily used for a single server installation. The second type is a ‘Cluster’ install which is where ViciDial is using multiple servers to function. The actual installer is the same for both options but the ‘Express’ install has predetermined settings given to the installer making it the least involved to set-up.

For a new ViciBox/ViciDial admin it is recommended to start with an Express install to familiarize yourself with the installation process. If there is a possibility that within the next month or two after install the server might grow beyond supporting 20 agents it is recommended to start with mutliple servers and do a ViciDial cluster. An express install can be migrated to a cluster install at a later time but the it takes a bit of knowledge and understanding of how the back-end processes of ViciDial work.

ViciDial Express Installation
 1.	If not already please login as the ‘root’ user to get to the root prompt. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 2.	At the root prompt type ‘vicibox-express’ and press the ENTER key. This will start the installation wizard. Follow the prompts to continue installation.
 3.	After the installation has finished, type ‘reboot’ and press the ENTER key to reboot the server. You should carefully examine the output of the installer to make sure that it installed properly. Do not assume that just because it finished it had successfully installed.
 4.	From a web browser on a desktop type in the IP Address of FQDN of your server and press the ENTER key.
 5.	If the installation was successful you should see the ViciDial Welcome page.

ViciDial Cluster Installation
 1.	If not already please login as the ‘root’ user to get to the root prompt. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 2.	On the database server at the root prompt type ‘vicibox-install’ and press the ENTER key. This will start the installation wizard. Follow the prompts to continue installation making sure to indicate that this server is the DataBase. If using any custom database settings please write them down for later reference on the Web and Telephony servers.
 3.	If you have a database slave server, please login as the root user on the slave server. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as a root user.
 4.	On the slave server at the root prompt type ‘vicibox-install’ and press the ENTER Key. This will start the installation wizard. Follow the prompts to contiue and make sure to select Expert Options and indicate that this is a slave database server. If you used any custom database configurations from Step 2 you will need to input them here.
 5.	Once the database(s) has finished installing, please login as the root user on the Web server. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 6.	On the Web server at the root prompt type ‘vicibox-install’ and press the ENTER key. This will start the installation wizard. Follow the prompts to continue installing and make sure to indicate that this server si the Web server. If you used any custom database configurations from Step 2 you will need to input them here.
 7.	Repeat step 4 for any additional Web servers you might have.
 8.	If you will be using a ViciBox server for an Archive server, please login as the root user on the archive server.Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 9.	On the archive server at the root prompt type ‘vicibox-install’ and press the ENTER key. This will start the installation wizard. Follow the prompts to continue installation and make sure to indicate that this is an Archive server. If you used any custom database configurations from Step 2 you will need to input them here.
 10.	Once the Web server has finished installing, please login as the root user on the Telephony server. Steps 19 and 20 from the Phase 1 installation instructions cover how to login as the root user.
 11.	On the Telephony server at the root prompt type ‘vicibox-install’ and press the ENTER key. This will start the installation wizard. Follow the prompts to continue installation and make sure to indicate that this is a Telephony server. If you used any custom database configurations from Step 2 you will need to input them here.
 12.	Repeat step 7 for any additional Telephony servers you might have.
 13.	When all servers in the cluster have been successfully installed it is recommended to reboot them to load things cleanly.

When doing a cluster installation it is possible to consolidate server roles during the install by inputting the proper options into the vicibox-install wizard. For example, if one server was going to be both the DataBase and Web Server you would say Yes to both the DataBase and Web Server questions during the install. The recommended minimum cluster installation is two server. One server to be the DataBase and Web server and the second server to act as a dedicated Telephony server.

Please refer to the ViciDial manual for further instructions on logging into ViciDial and configuring the various options. The default Admin user is ‘6666’ with a password of ‘1234’.

Please use caution when selecting ViciDial passwords such as the phone registration password. If you keep the passwords too simple you open yourself up to hackers committing toll fraud through your system. A secure password contains more then 8 characters and consists of one lowercase letter, one uppercase letter, and one numeral. An example of a secure password would be 'nebl6HE0u25a0Gt'. Please DO NOT use this password, it is ONLY an example. The default phone registration password and server password has already been randomized during the install. When changing them, please keep the above secure password requirements in mind.