Installation Manual for ViciBox v.7.0
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.1 documentation located at http://activedoc.opensuse.org/.

ViciBox is a self-contained installation CD based upon the OpenSuSE v.42.1 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 cluster 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.

Compatibility and Prerequisites

As of this writing the current version of ViciBox is v.7.0.0. It is built with the following software:
•	OpenSuSE Leap v.42.1
•	Linux Kernel v.4.1.15
•	Asterisk v.11.21.0-vici
•	DAHDI v.2.11.0
•	Amfeltec VoiceSync v.1.3.8
•	OpenR2 v.1.3.3

For an optimal experience with ViciDial and ViciBox, the following minimum hardware specifications should be used:
•	Quad-Core CPU 2.0Ghz
•	4GB RAM
•	160GB 7200rpm enterprise-grade SATA drive (Seagate ES, Hitachi UltraStar, WD RE4, etc)

Optionally, in addition to the above specifications, the following can be used for a more robust server:
•	8GB RAM (ECC if available)
•	Two hot-swap 500GB enterprise-grade SATA  or SAS drives in RAID-1
ViciBox “Express” 

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.

ViciBox “Cluster”

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.

A minimum starting cluster would consist of a single Telephony server and a combined Database and Web server. A three server cluster, whereby there is at least a single server dedicated to performing the roll of a Database, Web, and Telephony server is the more robust option and requires little to no reconfiguration as the cluster grows in size.

ViciDial scales horizontally for all roles except the Database. For this reason, you will need to spend extra time deciding on the hardware specifications of your Database server. The specifications we recommend for a database server up to 150 agents is as follows:
•	Quad-Core CPU 2.0Ghz+
•	8GB ECC Ram
•	2-drive 240GB+ SSD (Intel 530, 730, etc) configured in RAID-1 on a Linux software RAID or SSD-optimized raid card (LSI FastPath MegaRAID, etc)
•	Redundant Power Supplies with each on a different battery back-up

To add to the above specification for handling up to 300 agents would be as follows:
•	Two Quad-Core CPU 2.0Ghz+
•	16GB ECC Ram
•	Two Separate 500GB enterprise-grade SATA drive for the OS in a RAID-1

For a 500 agent Database server, adding to the specification, would be as follows:
•	Two Hex-Core CPU 2.0Ghz+
•	32GB+ ECC Ram
•	4-Drive 240GB+ RAID-10 on SSD (Intel 530, 730, etc) with SSD-optimized RAID card (LSI FastPath MegaRAID, etc) or Linux software RAID
•	Two Separate 500GB enterprise-grade SATA drive for the OS in a RAID-1

Cluster Dimensioning

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.

Below are some examples of dimensioning for various agent loads:

50 Agents Outbound 4:1
•	Optional Hardware Specification for Database/Web
•	Two Telephony Servers - Standard or Optional specification

75 Agent Outbound 4:1
•	Standard Database specification
•	One Web server – Standard or Optional specification
•	Three Telephony servers - Standard or Optional specification

100 Agent Outbound 4:1
•	Standard Database specification
•	One Web server – Standard or Optional specification
•	Four Telephony servers - Standard or Optional specification

200 Agent Outbound 4:1
•	300-agent Database specification
•	Two Web servers – Standard or Optional specification
•	Eight Telephony servers - Standard or Optional specification
•	Optionally one Web server to act as login load balancer and administration – Standard or Optional Specifications

500 Agent Outbound 4:1
•	500-agent Database specification
•	Four Web servers – Standard or Optional Specification
•	Twenty Telephony Servers - Standard or Optional Specification
•	One web server to act as login load balancer and administration - Standard or Optional Specification

100 Agent Inbound
•	Standard Database Specification
•	One Web server – Standard or Optional specification
•	Two Telephony servers - Standard or Optional specification

200 Agent Inbound
•	300-agent Database specification
•	Two Web servers – Standard or Optional specification
•	Four Telephony servers - Optional specification
•	Optionally one Web server to act as login load balancer and administration – Standard or Optional Specifications

500 Agent Inbound
•	500-agent Database specification
•	Four Web servers – Standard or Optional Specification
•	Ten Telephony Servers - Optional Specification
•	One web server to act as login load balancer and administration - Standard or Optional Specification

A dedicated Archive server was not listed in any of the above dimensioning guidelines but will be needed for most cluster installations. While ViciBox does provide an option to install as a dedicated Archive server it is not required to do so. Any NAS or server that can provide FTP for ViciDial to upload recordings and then HTTP service to access those recordings via a web browser can be used as an archive server. We recommend you have at least 1TB of space available on an archive server for storage. Hardware requirements for ViciBox to install as an archive server are minimal. A dual-core CPU and 2GB or more of RAM is all that is needed. It is highly recommended that you use at least a RAID-1 on your archive server to prevent data loss.

It should also be noted that the Telephony server role is limited by software and not hardware during dimensioning. This means that it does not scale linearly with hardware specifications. If you doubled the hardware capacity you would not double the call or agent handling capacity. This is because of the manner in which Asterisk scales starts to break down around or above 250 concurrent internal channels. Considering one agent in a call can potentially use 4 active internal channels we chose 25 agents outbound as our general rule of thumb. There is no imposed limit to prevent you from putting as many agents or calls on a server as you want, but the chances of the asterisk process crashing resulting in your call center being down greatly increase above the guidelines given. It is the opinion of the ViciDial Group that it is better to have an extra server and gain stability in the process. This is also cheaper once you calculate the cost of an hour of downtime versus the cost of the spare server.

Installation Notes

The standard 'root' password is 'vicidial' on all installion media. To login you simply type 'root' at the “Login” prompt and 'vicidial' at the “Password” prompt.

ViciBox is available only in a x86_64 64-bit architecture. It is not available in a 32-bit architecture or for non x86 based architectures like ARM or PowerPC. Any modern CPU released after 2004 should not have any issues installing or running ViciBox.

ViciBox v.7.0 ships by default with Asterisk v.11 installed. If you are adding a Telephony server to an existing cluster using ViciBox v.7.0 it will be necessary to either upgrade the cluster to a recent version of ViciDial that has Asterisk v.11 support or downgrade Asterisk to v.1.8. Downgrading Asterisk is not included as part of this installation manual.

Virtualization is NOT recommended for any portion of ViciDial except the Archive server. Due to the nature of ViciDial all components operate in a real time capacity. This is especially true for the Telephony server since it handles the RTP audio from agents and carriers. Virtualized installations will not be supported by the ViciDial Group. Support for virtualized installations may be available through the ViciDial forums.

The documentation is split up into two mandatory phases and one optional phase. Phase 1 consists of installing the Operating System onto the server and configuring the base requirements necessary for ViciDial to work. This includes things like RAID configuration, third-party drivers, and other considerations. Phase 1 must be completed and network connectivity established prior to any remote installation assistance. The server configuration, such as non-privileged users and network configuration, can be set here. 

Phase 1.5 are optional and recommended installation steps. This phase is primarily used to update the operating system with any relevant updates and configure additional options like the Date and Time, etc. This would also be the appropriate time to do any custom work to the operating system and it's configuration prior to the installation of Phase 2.

Phase 2 is the final installation step that installs and configures ViciDial on the server. This step should only be done when the server is in it's final production environment. If this is a cluster installation, then the Database server MUST be completed prior to attempting any other servers. The installer will not allow an install where it can not connect to the Database. If you have a planned Archive server using ViciBox, that should be installed prior to any Telephony servers. After installing the database, it's recommended to install the web server, archive server, and then telephony servers in that order. Telephony and Web servers should have the phase 2 installation done one at a time to prevent any issues.

Some conventions used throughout the installation instructions are as follows:
•	Commands to type will be contained within a single quote and should be typed exactly as how it appears between the quotes, example: `command here`
•	Keys to press on the keyboard will be in all caps; three examples: ENTER ESC F3
•	Key sequences, or a multiple key press, will be capitalized with a dash between each key to press simultaneously; five examples: ALT-N ALT-Q CTRL-I CTRL-ALT-F1
•	Commentary and Notes will be italicized explaining various options or explanations for that stage of the installation.
•	Each section has a paragraph explaining the objective of that phase of the installation, as well as a footer saying where to proceed to the next section.
•	The command prompt is signified by a red pound (#) sign and the cursor. Example: linux # 

Phase 1 – OS Installation

To perform the OS Installation using the standard ISO perform the following steps:
 1.	Download the current ViciBox Server ISO from http://download.vicidial.com/iso/vicibox/server/
 2.	Burn ISO to CD/DVD and boot from the disk
 3.	At the boot screen, press the F3 key to select the Video Mode options
 4.	Using the arrow keys, highlight the 'Text Mode' option and press the ENTER key
 5.	Using the arrow keys, highlight the 'ViciBox v.7' option in the center of the screen and press the ENTER key.
 6.	At the ViciDial license screen, press CTRL-A to agree to the license agreement
 7.	Press ALT-N to select 'Next' and proceed with the boot-up sequence
 8.	At the login prompt, type 'root' and press ENTER. You may have to hit ENTER after a minute to see the login prompt. It sometimes gets overwritten on the screen from the boot process.
 9.	At the Password prompt, type 'vicidial' and press ENTER
 10.	At the command prompt, type 'os-install' and press ENTER. If there is any custom configuration to be done to this server prior to OS installation, it should be done before this step.
 11.	To change the default langauge, press ALT-L and select your preferred language
 12.	To change the default keyboard layout, press ALT-K and select your preferred layout
 13.	Press ALT-N to agree to the license displayed and move on to the next screen
 14.	To change the displayed region, press ALT-E and use the up and down arrow keys to select your preferred region. Alternatively, the TAB key can be used to switch between windows on this screen and proceeding screens.
 15.	To change the displayed Time Zone, press ALT-Z and use the up and down arrow keys to select your preferred time zone.
 16.	Press ALT-N to accept the selected Region and Time Zone and move on to the next screen
 17.	To accept the default partitioning scheme press ALT-N to proceed to the next screen. The partitioning module in OpenSuSE is somewhat inconsistent. You should see in the summary list "Create swap volume /dev/sda1" and "Create root volume /dev/sda2". If not, please read the partitioning notes under the Miscellaneous section at the end of this document prior to proceeding.
 18.	Type in the new 'root' password that you would like to use. For the purposes of this document you would type 'vicidial'.
 19.	Press ALT-F to move to the password confirmation dialog, and re-type in the new root password you entered in the previous step.
 20.	Press ALT-N to select Next and continue with the installation. If the passwords to not match, are blank, or are not considered high-security passwords, you will be presented with an additional dialog box. You will need to either correct the passwords if they are blank or don't match, or chose whether to accept the password and continue or input a new password.
 21.	Press ALT-I to install the operating system according to the installation summary presented. You can use the up and down arrows keys to scroll through the installation summary. You can press ENTER on any highlighted section to adjust those installation options, although those options will not be covered by this document. This is the point of no-return, do not proceed past here if this server already has important data on it.
 22.	Press ALT-I to confirm the destruction of the host system's old installation and installation of the new operating system. You will be presented with a screen showing installation progress and logs. At this point all data on the hard drive has been destroyed.
 23.	When prompted, press ALT-N and then press ENTER to reboot the server. You may also use the left and right arrow keys to highlight "Reboot Now" and press ENTER. It is a good idea to remove the CD from the drive during reboot as well as setting the BIOS to boot from the hard-drive before any other devices.
 24.	When the Login prompt comes up after the reboot, log in as the 'root' user using the password entered in step 18 above.
 25.	At the command prompt, type 'reboot' and press ENTER. Due to a quirk in the OpenSuSE LiveCD installer it is necessary to reboot the server a second time to properly initialize the network. This is only required once after the LiveCD has finished it's installation.

The Phase-1 OS Installation is now complete. Please proceed to the Phase 1.5 installation instructions. You will need to complete the required portions of Phase 1.5 before continuing to Phase 2.

Phase 1.5 – Required, Recommended, and Optional configuration items

This section contains small miniaturized installation and configuration instructions for various things. The only required section is the "Network Configuration" section. It is required that all ViciDial servers be able to communicate freely with each other on the network. The other sections include recommended and optional configuration information.

Phase 1.5 - Network Configuration   REQUIRED CONFIGURATION
 1.	If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the password prompt. If you changed the root password, or someone else has, you will need it to login. The password can not be recovered easily and requires offline intervention.
 2.	Type 'yast lan' and press ENTER Optionally, you can type 'yast' and navigate to the network configuration by going to Network Devices --> Network Settings.
 3.	Using the TAB key, press it until the network card is selected. If you have multiple network cards, select the one that will be used to communicate with the other ViciDial servers.
 4.	Press ALT-I to edit the network configuration for that interface.
 5.	Press ALT-T to select "Statically assigned IP Address". The server should always have a statically assigned IP address, no exceptions.
 6.	Press ALT-I to move the cursor to the "IP Address" field, it should be highlighted. Optionally, you can use the TAB key to move between fields and windows on this screen and the proceeding screens.
 7.	Enter the IP Address for this interface. This should primarily be the internal IP Address if this is the first network card. If this is the second network card, this would be the IP Address provided to you by your ISP if not behind a router.
 8.	Press ALT-G to view the General options for this network card.
 9.	Press ALT-Z to select the Firewall Zone for this Interface.
 10.	Using the up and down arrow keys, select "Internal Zone" and press ENTER. If this is the second network card connected directly to the internet, select "External Zone" instead. Optionally, if you are going to disable the built-in firewall, select "Internal Zone" for all network cards to prevent the system from being locked out should the firewall be turned on by mistake.
 11.	Press ALT-N to accept network card configuration and return to the Overview screen. Optionally, if you have a second network card to configure, you can repeat steps 3 to 11 by select the second network card in step3.
 12.	Press ALT-S to change to the Hostname/DNS screen
 13.	Press ALT-T to select the Hostname field
 14.	Enter the unique Hostname of this server. All servers MUST have a unique hostname for the installation to properly continue. The installer will fail if all hostnames are not unique. We recommend using DB(x), Web(x), and Vici(x) for the hostnames while replacing the (x) with the numerical sequence of the installed server. For instance, the first Web server would be Web1, the second Web server would be Web2, the first Telephony server would be Vici1, the second Telephony server would be Vici2, etc. Try to choose a hostname that relates to the function of the server and not an arbitrary name to avoid confusion. Names like 'Zeus', 'Batman', 'Mickey Mouse', etc, do not properly convey the function of the server to anyone who may be unfamiliar with it.
 15.	Press ALT-D to select the Domain field
 16.	Enter the Domain name for this server. If you do not have or know your Domain, enter 'vici.local'.
 17.	Press ALT-1 to select Name Server 1 field
 18.	Enter the primary name server to use on your network. If you are behind a router this is typically the router IP. If you do not have or know your DNS server's IP then enter '8.8.8.8' to use Google's DNS.
 19.	Press ALT-2 to select Name Server 2 field
 20.	Enter the secondary name server ot use on your network. If you do not know or have a secondary DNS server, then enter '8.8.4.4' to use Google's DNS
 21.	Press ALT-U to change to the Routing screen
 22.	Press ALT-F to select the Default IPv4 Gateway field
 23.	Enter the default gateway IP for your network. This will be the IP address of your router. This is determined by your local network/router and can not be determined remotely. If you have a second network interface card that is directly connected to an ISP then you will enter the gateway IP provided by the ISP here.
 24.	Press ALT-O to select Ok and make the network configuration changes. You can review the changes by pressing ALT-V for the overview, ALT-S for the Hostname/DNS configuration, and ALT-U for the routing configuration if you want to review them before proceeding.
 25.	Verify proper network connectivity by trying to ping something on the internet, I.E. 'ping google.com'. Press CTRL-C to stop the ping when satisfied. If you do not have internet connectivity try pinging another server or workstation on the network. Depending upon the complexity of your network configuration it might be necessary to reboot to enact network configurations.

In addition to basic network configuration, you can configure the built-in firewall by typing 'yast firewall' or select Security --> Firewall after typing 'yast'. The Phase 2 installation script will ask you if you want to enable or disable the firewall and will automatically open up the appropriate ports for ViciDial to function if left enabled. You only need to configure advanced options if wanted.

Phase 1.5 – Install Updates Recommended
 1.	If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the password prompt. If you changed the root password, or someone else has, you will need it to login. The password can not be recovered easily and requires offline intervention.
 2.	Type 'zypper up -y' to begin the update process. If this step fails, then try again later. The OpenSuSE repositories go into maintenance at certain times and can be unavailable, making updates impossible to happen.
 3.	Type 'reboot' to cleanly load and apply any updates that were applied to your system.

Phase 1.5 – Configure Time Zone Recommended
 1.	If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the password prompt. If you changed the root password, or someone else has, you will need it to login. The password can not be recovered easily and requires offline intervention.
 2.	Type 'yast timezone' to enter the time zone configuration screen
 3.	 Type ALT-R to move to the region selection window.
 4.	Using the up and down arrow keys, select the appropriate region for this server's location.
 5.	Type ALT-Z or press TAB to move to the Time Zone window
 6.	Using the up and down arrow keys, select the appropriate time zone for this server's location.
 7.	Type ALT-O when finished to accept the configured region and time zone for this server.

Phase 1.5- Changing the root password Optional (Read completely first)
 1.	If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the password prompt. If you changed the root password, or someone else has, you will need it to login. The password can not be recovered easily and requires offline intervention
 2.	Type 'passwd' at the command prompt to start the password change processes
 3.	Type in the new root password at the “New Password:” prompt and press ENTER
 4.	Verify the password by typing it in again at the “Retype new password:” prompt and press ENTER.

DO NOT LOSE THIS PASSWORD! It is always required for any remote support needed at the operating system level and can not easily be recovered. Please chose a password that contains letters and numbers and is at least 8 characters long. Mixing upper and lower case letters is advisable and specialty characters like @ = / + - ! ~ can also be used.. Avoid choosing passwords that are overly complex, random, or hard to remember. This just leads to people writing the password down and leaving it stuck to their monitor.

One simple method is to take a word and replace a few letters with numbers and capitalize it. For instance, if we take the standard root password 'vicidial' and apply this logic we would end up with 'V1c1d1al'. While 8 characters is the minimum recommended length, 12 or more characters is optimal. Avoid using a strong password generator as the password will almost assuredly be forgotten or written down which negates the whole point of a strong password to begin with. Also do not use any password contained within this document or used as an agent/manager login. The root password should be unique and not shared with anyone other then system administrators.

If the 'ssh' service (TCP Port 22) is not exposed or connected to the internet to begin with then it is arguably safe to leave the stardard root password of 'vicidial'. If the server IS accessible via SSH from the internet then it is highly recommended to change the root password or otherwise restrict access to it externally. If someone is able to log in as root they will be able to do whatever they want with your server. Most of the time this involves using your system for Spam, DDoS attacks, bitcoin mining, and toll fraud. All of which have a very detrimental effect on your ViciDial system.

Phase 2 - ViciBox "Express" Installation

This section contains installation instructions for the "Express" installation method of ViciBox. Please read the "ViciBox Express" section at the beginning of this document before continuing. The time required to split an Express installation into a cluster later can easily surpass the amount of time normally required to set-up a Cluster from the start.

To install ViciDial using the ViciBox "Express" method, run the following:
 1.	If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the password prompt. If you changed the root password, or someone else has, you will need it to login. The password can not be recovered easily and requires offline intervention.
 2.	Type 'vicibox-express' and press ENTER. You will see the installer start in ViciBox Express mode. It will prompt for any further input it needs while installing.
 3.	When the installer indicates that it has completed, type 'reboot' and press ENTER to reboot the system and cleanly load all changes and ViciDial.
 4.	From a web browser on a workstation, type in the IP Address of your server and press ENTER.
 5.	At this point you should see the ViciDial welcome page. The installation is now complete.

Please refer to the ViciDial Manual for further instructions on logging into ViciDial and configuring the various options. The default administrative user for ViciDial is '6666' with the password of '1234'. You do not need to complete any other Phase 2 instructions at this point.

Please use caution when selecting system passwords. 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 in your install. When changing them, please keep the above secure password requirements in mind.

Phase 2 - ViciBox "Cluster" Installation

This section contains installation instructions for the "Cluster" installation method of ViciBox. Please read the "ViciBox Cluster" section at the beginning of this document before continuing. A cluster with underpowered resources can potentially cause problems that could result in downtime and loss of productivity. Server downtime can easily outweigh the financial savings from under-powering a Cluster. Free community support is available on the forums as well as paid support through the ViciDial Group if you have any questions on properly dimensioning or installing a cluster.

Due to the nature of clustering and the ViciBox installer, all clusters, regardless of size, must be installed in the following order:
 1.	Database Server
 2.	Archive Server if applicable
 3.	Web Server
 4.	Telephony Server

The installer will refuse to run without being able to properly connect to the database. If you have a slave database, make sure you are putting in the IP Address of ONLY the master database when the installer asks. You must also have at least one Web server installed prior to installing any Telephony servers in order for the Audio Store and other web-based ViciDial features to be properly set-up and enabled. Best practice is to run the installations linearly, starting with the DB server and progressing your way on to the next server only when the current one has completed it's install. This ensures that things are installed properly and in the right order to prevent any issues.

Make sure to write down the IP Address' of all your servers so that you can refer to them later during the installation. This will not only help during the installation but also shorten the time it takes to diagnose and correct any issues that may come up. If possible, map out your IP address' so that they are linear in progression and make sense. For instance, 192.168.0.10 would be a database, following by 192.168.0.11 for the web server, and then 192.168.0.12 and above for the telephony servers.

To install ViciDial using the ViciBox "Cluster" method, run the following:
 1.	If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the password prompt. If you changed the root password, or someone else has, you will need it to login. The password can not be recovered easily and requires offline intervention.
 2.	Type 'vicibox-install' and press ENTER. The installer will start and prompt you for all further configuration information.
 3.	When the installer indicates that it has completed, type 'reboot' and press ENTER to reboot the system and cleanly load all changes and ViciDial.

Installation of a cluster can not be verified until the Web server is installed at a minimum. To verify, type the web servers IP address from a workstation and you should see the ViciDial welcome page. The default administrative user is '6666' and password '1234'. Please refer to the ViciDial Manual for information on initially logging in and configuring ViciDial from the web interface.

Once you have logged into the web interface, you can verify that the cluster is working properly by clicking on the Report section on the left, and then clicking the + next to where it says "Server" at the bottom. It will list the time on all connected machines in the cluster. When properly set-up, all machines should be within one to two seconds of each other with the exception of the Database server entry. You should all see all the hostnames of the Telephony server and the Database server. It is correct for the Database server entry to not show the correct time, however, at the bottom the "DB Time" field should match.

Phase 2 - ViciBox "Restore" Server Replacement in a Cluster

The restore method is not a complete end-all solution for replacing a server in a ViciBox cluster. It is a tool mean't to ease and speed the replacement of a server. It can not be used for a database and does not copy any custom configurations, crontab entries, or other things done on a server. It is advised you maintain back-ups of your servers to prevent data loss and additional downtime during replacement.

In order to use the restore option you will need to know your database connection information. If the database was installed with ViciBox prior to v.4.0 or then you will also need to know the SVN revision running on your cluster. The safest method for determining the SVN revision it to run 'svn info' in the /usr/src/astguiclient/trunk directory on your database server. If your database was not installed using ViciBox then you will have to ask the system administrator what SVN revision was used.

To run the ViciBox restore, perform the following commands:
 1.	If not already, login as the root user by typing 'root' at the login prompt and 'vicidial' at the password prompt. If you changed the root password, or someone else has, you will need it to login. The password can not be recovered easily and requires offline intervention.
 2.	Type 'vicibox-install --restore' at the command prompt and press ENTER. The installer will start in the special restore mode and prompt you for further information.
 3.	When the installer indicates that it has completed, type 'reboot' and press ENTER to reboot the system and cleanly load all changed and ViciDial.

ViciBox Upgrade

There are currently two methods for upgrading ViciBox. Method one is to do all steps and procedures manually according to the documentation located at /usr/src/astguiclient/UPGRADE. The second method involves using a program called 'vicibox-upgrade' to perform the schema and SVN upgrade for you leaving just the changes to configuration files. The vicibox-upgrade program will also add the vicibox table on the database if it doesn't exist making your cluster compatible with newer features introduced since ViciBox v.4.0.

The preferred method is to start on the database. It is highly advised you take a back-up of the database prior to performing the upgrade. Once the database is done you would then run vicibox-upgrade on the web servers, followed by the dialers. You can use the --help flag to view all run-time options. Please keep in mind that the upgrade program does not modify any configuration files like /etc/asterisk/extensions.conf. These will still need to be upgraded by hand. This is merely a tool to help upgrade the database and make sure the same SVN revision is installed on all servers.

The program has been tested to run properly on ViciBox v.3.0 and above. You can simply copy it to the older servers to use it's features. As mentioned previously, always start with the database first. It is imperative that the database be upgraded first before any other systems in a cluster are attempted. If you are upgrading an 'express' installation then you only need to run vicibox-upgrade once.

When ran on a system that was installed prior to ViciBox v.4.0 you will be prompted for the roles that each server performs. You will then be prompted on whether or not to insert the records into the vicibox table if it exists at the end of the upgrade. The recommendation is to say Yes to inserting the records into the vicibox table. This will help in the maintenance of your installation in the future.

Miscellaneous, Tips and Tricks, Issues, and other commentary

Installation Partitioning

The partitioning module included in OpenSuSE has become less consistent in how it calculates the partitioning scheme. The default paritioning scheme that it should be creating consists of a 4GB "swap" partition and a "/" root partition containing the rest of the drive. Unfortunately this does not work consistently if there was a previously installed linux swap partition. Instead it will use that swap partition, create another 4GB partition, and then configure the rest of the drive as the "/" root partition. The easiest way to fix this is to wipe out the partition table using the following command from the LiveCD prior to typing 'os-install' during Phase 1:

 1.	Type 'dd if=/dev/zero of=/dev/sda bs=512' and press ENTER
 2.	Type 'reboot' to reboot the server and re-attempt your install

CAUTION: Do not run this command on any active server as it will destroy all data on the drive requiring a specialist to recover it. You have been warned!

Expert Mode Options

The "Cluster" installer includes an expert mode to enable extra options for those who needs them. If you are not that familiar with Linux or ViciDial then most likely you do not need any of the options offered by expert mode. Improperly setting things in expert mode can have a detrimental effect to the efficiency and operation of a cluster.

Below are the extra prompts offered by the expert mode install:
•	Slave Database installation
•	Install index.php to redirect user to the ViciDial welcome screen (enabled by default)
•	Install phpMyAdmin (disabled by default)
•	Supply connection settings for use by the Archive server role

Legacy Mode

Legacy mode enables support for legacy ViciDial installs not installed using ViciBox v.4.0+. Your installation must be using an SVN "Trunk" Revision in order to be compatible with ViciBox v.4.0. You will also need to know what SVN revision your other servers are using in order for ViciBox to complete it's install. A method to add the 'vicibox' table used by ViciBox v.4.0+ to older installations is currently planned but not available yet.

The 'ngrep-sip' command

There is an amazingly useful but little known utility that has been included in ViciBox v.3.1+ called 'ngrep-sip'. What this does is use ngrep, a network-grep'ing utility', and scans for SIP traffic. It's use is pretty straightforward, you type 'ngrep-sip' and it gives SIP output. In addition to this, you can scan for SIP traffic to a certain host or for a specific phone number. For instance, if you want to see the SIP messages going to phone number 8633939330, you would run 'ngrep-sip 8633939330'. It will then only show you SIP messages that have that phone number in it. You can also use host to specify only a certain host. So if you wanted to see SIP messages going to a new carrier with IP A.B.C.D, you would type 'ngrep-sip host A.B.C.D'. You can also capture these messages to send to carriers when they inevitably tell you everything is great but they are broken. It should be noted that ngrep-sip does not display correctly when using VLANs on your network, but it is still close enough to be readable if you understand SIP messaging. There is a config file located at /etc/ngrep-sip.conf if you want to change the standard network interface it listens to when ran. Remember, with all carriers, you are wrong until YOU have proven otherwise.

The 'mysql-tuning' command

The 'mysql-tuning' script will look at your currently running MySQL configuration and give you generalized recommendations on tuning your my.cnf settings as well as show where any potential problems are. This is especially useful for when things seem to be slowing down but nothings looks obviously wrong. This is useful for when you hit your MySQL configured max connection limit. It will also show you if you have ever allocated more memory then you have RAM which means you swapped out to disk. All very useful things, but it is not 100% accurate in it's recommendations. It is merely a tool used to guide you in the diagnosis of a problem. It should not be used for fine tuning but for diagnostic and broad tuning.

Zoiper Web Phone is installed

The zoiper web phone is installed by default on all version of ViciBox and works for up to 3 minutes if you want to test it. The web phone is Windows only and best installed initially from Internet Explorer. Point IE to http://webserver.ip/agc/webphone/ and it should download and install. Once installation is complete, the webphone works from IE, FireFox, and Chrome. The Zoiper Web Phone License can be purchased from the ViciDial Group and installed for you or you can purchase it directly from Zoiper and install it. The web phone is based upon your fully qualified domain name (FQDN) and is non-refundable once issues. This means that if you tell them to generate the license for http://my.webserver.com and you then later decide you wanted it to be http://some.webserver.com the license will not work. You will have to purchase a second license for the new FQDN or stay with the old server name. You also need to use a domain name as it will not work with IP Addressing directly.

Integrated ipset with built-in firewall

IPSet has been integrated with the build in SuSEfirewall2 script to provide a simple mechanism to block malicious IP address'. This is a simple IP hash list of single IP address' that are set in an iptables rule to drop any packets sent to or received from them. You can view the IP's in the list by typing 'ipset -L badips' and pressing ENTER. To add an IP to this list you would type 'ipset add badips X.X.X.X' replacing the X.X.X.X with the offending IP. To remove an IP from this list you would type 'ipset del badips X.X.X.X' replacting the X.X.X.X with the IP to remove. There is currently no facility in place to save and manage the IP's that are put into this list so any data put in IPSet will be lost upon reboot. To have the IP's persist after reboot you can add the command to add the individual IPs to the end of the /etc/init.d/after.local file. This will make sure any IP you block will stay blocked.

VoiceMail spool manager utility

A utility has been added to vicibox located at /usr/local/bin/vmspool_manager.pl. It's primary purpose is to allow you to trim voicemail boxes of any messages older then X days. You would use it by logging into the server and typing 'vmspool_manager.pl --age=X --active' replacing X with the number of days that voicemail should be kept. For instance, replacing X with 14 will delete any voicemails that are older then 14 days. You can also use --mailbox=Y to only look through certain mailboxes as opposed to all mailboxes on the system. It is recommended to run this periodically if you are not emailing and deleting voicemails by default.

Feedback and Community Support

We like hearing from you. Whether it is bugs, condemnation, or praise, we like it. It helps us to improve both ViciDial and ViciBox. Without your feedback things will not improve or move in the direction the community wants it to. Please take some time to log into the community forums at http://www.vicidial.org/VICIDIALforum/ and let us know how you did, good or bad. You will find the array of talent available there to be excellent as well as the breadth of knowledge already posted.

Please remember to search for any issues or topics prior to posting to see if your question has already been answered. In addition to getting you your answer quicker, it also makes others more likely to respond when they know you searched first.

When posting on the forum, it is considered proper etiquette to state what installation medium you used, what the ViciDial Admin and Build date are from the administration interface, what SVN revision you are using, and any other pertinent information that might relate to your issue or bug. For instance, using the version of ViciDial shipped on ViciBox v.4.0.0, with a 75-agent outbound cluster using the dimensioning mentioned previously, you would want to include the following in your post so we know how best to start helping you:

ViciBox v.4.0.0 32-bit preload
Build: 120831-1528
Version: 2.6-375a
SVN Rev: 1858
1xDB, 1xWeb, 3xTelephony, 1x Archive

Credits and Thanks

Thanks go out to all the active members of the ViciDial Community Forums and those companies and individuals who sponsor features in ViciDial and ViciBox. These guys make things happen and push us to release bigger and better versions of ViciDial and ViciBox. They have committed code snippets for improving functionality, paid for features that everyone gets to use, and beta tested early versions to try and find bugs before general release. Stop by and say thanks, they like it.

ViciDial was initially written and copyright by Matthew Florell.
ViciBox was conceived and initially written by Michael Cargile from the ViciDial Group.
ViciBox is currently written and maintained by James Pearson from the ViciDial Group.
Iterative testing and verification performed by Keith Hughes, Robert Reeder, Michael Coate, and Matt Borchert from the ViciDial Group.