Agent Installation

A user with root privileges can install the Agent on a physical or virtual machine meeting minimum system requirements. As of this writing, the Agent has been tested on RHEL/CentOS 7.4 and 7.5.

Before You Begin

Ensure that firewalld is installed. If not, install, start, and enable firewalld

yum install firewalld
systemctl start firewalld
systemctl enable firewalld

Add the Ethernet interface to the public zone. The interface is typically named eth0. If the interface has a different name, be sure to use that name in the following command

firewall-cmd --permanent --zone=public --add-interface=eth0

Allow GRE and IPsec traffic

firewall-cmd --permanent --direct --add-rule ipv4 filter INPUT 0 -p gre -j ACCEPT
firewall-cmd --permanent --add-service="ipsec"
firewall-cmd --reload

If errors are encountered when starting the firewalld service, refer to the Troubleshooting & Debug for suggestions.

Installation

Install EPEL repository, which is required by strongSwan

yum install epel-release

Install Bayware’s repository

yum install https://repo.s3.bayware.io/public/bayware-repo.noarch.rpm

Before you can proceed with installing the Bayware Agent from the Bayware repository, you need an Access Key and An Access Key ID. These credentials are provided by Bayware. If you do not have these credentials please contact us <mailto:contact@bayware.io>.

Once you have your credentials, add them to the Bayware repo file as follows.

cd /etc/yum.repos.d

Using your favorite text editor, open the Bayware repo. This example uses vi.

vi Bayware-IceBreaker.repo

Look for the following lines in the file. They may not be in this order or even grouped together

enabled=0
key_id=<AWS_KEY_ID>
secret_key=<AWS_SECRET_KEY>

Enable the repository and assign your Access Key ID to key_id and your Access Key to secret_key. When you’re finished, the three lines should look similar to

enabled=1
key_id=AKIAJQLKJLXS5N6XL76B
secret_key=NR0SyUYSR0mSAkgzhKcFyMS1Bolyhw0p6CBTX6uw

Of course, you’ure key_id and secret_key will be different than those shown above.

Install the Bayware Agent (and strongSwan, which is installed as a dependency)

yum install ib_agent

Configuration

The ib_agent must be configured after installation. Executing the following script without parameters displays its help screen. Refer to the following text for an explanation on how to properly configure the Agent.

/opt/ib_agent/bin/ib_configure
Note
  • default installation dir = /opt/ib_agent
  • default configuration script dir = /opt/ib_agent/bin
  • default configuration file dir = /opt/ib_agent/conf

There are two ways to run the configuration script

  1. run ib_configure -i INTERACTIVE mode
    the user has the ability to input parameters one at a time or to simply accept the suggested values using return. If this is the first time running the script, default values are suggested. If this is not the first time running the script, parameters used previously and subsequently stored in ib_agent.conf are used.
  2. run ib_configure BATCH mode
    in batch mode, the script uses parameters from the command line or parameters stored in ib_agent.conf. Any parameter not supplied on the command line is taken from the configuration file. Any parameter supplied on the command line is subsequently stored in ib_agent.conf for future use. Note that at least one parameter must be configured from the command line when using batch mode. Running the script without any command-line parameters returns the help message show below.
[root@host]# ./ib_configure -h
usage: ib_configure [-h] [-i] [-o OUTFILE] [-s] [-c CONTROLLER] [-d DOMAIN]
                       [-l USERNAME] [-p PASSWORD]

Setup the Bayware Agent.

optional arguments:
  -h, --help            show this help message and exit
  -i, --interactive     Setup configuration parameters interactively
  -o OUTFILE, -f OUTFILE, --outfile OUTFILE
                        Output file
  -s, --ipsec           Setup strongswan
  -c CONTROLLER, --controller CONTROLLER
                        IP-address of the Controller
  -d DOMAIN, --domain DOMAIN
                        Controller's Domain
  -l USERNAME, --username USERNAME
                        Controller's user name
  -p PASSWORD, --password PASSWORD
                        Controller's user password

Start Agent Service

After running the configuration script, start the Agent

systemctl enable ib_agent
systemctl start ib_agent

Check Installation

Both ib_agent and strongSwan should now be running as a service on the system. Confirm this

systemctl status ib_agent

The ib_agent service should be active and running, similar to the following

● ib_agent.service - SYSV: IceBreaker Agent
   Loaded: loaded (/etc/rc.d/init.d/ib_agent; bad; vendor preset: disabled)
   Active: active (running) since Wed 2018-05-09 22:25:24 UTC; 31min ago
     Docs: man:systemd-sysv-generator(8)
  Process: 6079 ExecStop=/etc/rc.d/init.d/ib_agent stop (code=exited, status=0/SUCCESS)
  Process: 6095 ExecStart=/etc/rc.d/init.d/ib_agent start (code=exited, status=0/SUCCESS)
   CGroup: /system.slice/ib_agent.service
           ├─6109 python /opt/ib_agent/bin/ib_agent.py -c start
           └─6110 python /opt/ib_agent/bin/ib_agent.py -c start

And for strongSwan

systemctl status strongswan

the output should be similar to

● strongswan.service - strongSwan IPsec IKEv1/IKEv2 daemon using ipsec.conf
   Loaded: loaded (/usr/lib/systemd/system/strongswan.service; disabled; vendor preset: disabled)
   Active: active (running) since Mon 2018-06-04 08:27:11 PDT; 7h ago
 Main PID: 16388 (starter)
   CGroup: /system.slice/strongswan.service
           ├─16388 /usr/libexec/strongswan/starter --daemon charon --nofork
           └─16401 /usr/libexec/strongswan/charon

Troubleshooting & Debug

Operating System & Libraries

The Agent has been tested on RHEL and CentOS 7.4 and 7.5. If the system is running an earlier version or the libraries on the system are outdated, the Agent may not run properly. If you are experiencing problems installing the Agent, it is recommended to update all packages

yum update

Firewalld & CentOS Upgrade

If starting firewalld results in an error message similar to

[centos@aws-16 ~]$ systemctl start firewalld
==== AUTHENTICATING FOR org.freedesktop.systemd1.manage-units ===
Authentication is required to manage system services or units.
Authenticating as: Cloud User (centos)
Password:
polkit-agent-helper-1: pam_authenticate failed: Authentication failure
==== AUTHENTICATION FAILED ===
Failed to start firewalld.service: Access denied
See system logs and 'systemctl status firewalld.service' for details.

then restart D-Bus service followed by firewallD service as follows

systemctl restart dbus
systemctl restart firewalld

This problem may be the result of upgrading the operating system from CentOS 7.4 to 7.5. It may also be corrected by rebooting the system.

Agent Discovery Protocol

Following installation, ensure that strongSwan (for IPsec implementations) and the Bayware Agent are both running properly.

When using IPsec, the Agent should be passing traffic through the GRE interface. The GRE interface is ib-gre0. Use tcpdump as follows

tcpdump -ni ib-gre0

You should see IPv6 traffic such as

listening on ib-gre0, link-type EN10MB (Ethernet), capture size 262144 bytes
19:18:40.244014 IP6 fe80:8300:2001:ffff:3487:d324:95b6:212e > ff02::1: ICMP6, neighbor advertisement, tgt is ff02::1, length 664
19:18:40.553510 IP6 fe80:8300:2001:ffff:20b3:ca1:13a5:9ea9 > ff02::1: ICMP6, neighbor advertisement, tgt is ff02::1, length 664
19:18:41.646974 IP6 fe80:8300:2001:ffff:3487:d324:95b6:212e > fe80:8300:2001:ffff:20b3:ca1:13a5:9ea9: ICMP6, neighbor solicitation, who has fe80:8300:2001:ffff:20b3:ca1:13a5:9ea9, length 664
19:18:41.655856 IP6 fe80:8300:2001:ffff:20b3:ca1:13a5:9ea9 > fe80:8300:2001:ffff:3487:d324:95b6:212e: ICMP6, neighbor advertisement, tgt is fe80:8300:2001:ffff:3487:d324:95b6:212e, length 664

IPsec Activity

You can also check strongSwan, which should indicate uplink. Type the command

strongswan status

or

strongswan statusall

The first, less verbose command shows something like

Security Associations (1 up, 0 connecting):
   ib_uplink[1]: ESTABLISHED 41 minutes ago, 172.31.34.40[CN=aws-15]...18.219.21.181[CN=aws-1]
   ib_uplink{1}:  INSTALLED, TRANSPORT, reqid 1, ESP in UDP SPIs: c070d092_i cc98cc3e_o
   ib_uplink{1}:   172.31.34.40/32 === 18.219.21.181/32

Also, /var/log/messages should indicate an established session. Type

egrep 'charon|strongswan' /var/log/messages | grep established

to see something similar to

Apr 24 18:43:08 aws-15 strongswan: 16[IKE] inbound CHILD_SA ib_uplink{11} established with SPIs c9b7f3c5_i cbb08e2d_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 18:43:08 aws-15 strongswan: 05[IKE] outbound CHILD_SA ib_uplink{11} established with SPIs c9b7f3c5_i cbb08e2d_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 18:43:08 aws-15 strongswan: 06[IKE] inbound CHILD_SA ib_uplink{12} established with SPIs c1d77a50_i c5200d58_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 18:43:08 aws-15 strongswan: 07[IKE] outbound CHILD_SA ib_uplink{12} established with SPIs c1d77a50_i c5200d58_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 18:46:33 aws-15 charon: 08[IKE] IKE_SA ib_uplink[1] established between 172.31.34.40[CN=aws-15]...18.219.21.181[CN=aws-1]
Apr 24 18:46:33 aws-15 charon: 08[IKE] CHILD_SA ib_uplink{1} established with SPIs c070d092_i cc98cc3e_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 18:48:40 aws-15 strongswan: 08[IKE] IKE_SA ib_uplink[1] established between 172.31.34.40[CN=aws-15]...18.219.21.181[CN=aws-1]
Apr 24 18:48:40 aws-15 strongswan: 08[IKE] CHILD_SA ib_uplink{1} established with SPIs c070d092_i cc98cc3e_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 19:29:14 aws-15 charon: 12[IKE] inbound CHILD_SA ib_uplink{2} established with SPIs ce93210c_i c233124a_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 19:29:14 aws-15 charon: 12[IKE] outbound CHILD_SA ib_uplink{2} established with SPIs ce93210c_i c233124a_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 19:36:20 aws-15 strongswan: 12[IKE] inbound CHILD_SA ib_uplink{2} established with SPIs ce93210c_i c233124a_o and TS 172.31.34.40/32 === 18.219.21.181/32
Apr 24 19:36:20 aws-15 strongswan: 12[IKE] outbound CHILD_SA ib_uplink{2} established with SPIs ce93210c_i c233124a_o and TS 172.31.34.40/32 === 18.219.21.181/32

Reference

Agent Configuration File

The Agent configuration file is located at /etc/ib_agent.conf. One can customize this file if the default values are not suitable.

Field Description
[agent]  
controller_ip The Controller’s IP address. The Agent module uses REST API to reach Controller at this address.
domain Name of IB overlay network used for authorization and determining Controller host_id
login Authorized name
password Password used for authorization
pid_file Full path to file that contains PID of running Agent process
log_file Full path to file used for logging records
log_level Defines logging verbosity. Acceptable values are CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET
log_level_dp Defines logging verbosity for data plane layer of Agent
[app_iface] Provides configuration parameters for network tunnel interface (TUN)
name Name of virtual network device
address IP address and netmask of interface in CIDR notation (e.g., 10.0.0.0/8)
mtu Maximum transmission unit
[net_iface] Provides configuration parameters for network TAP interface.
name Name of virtual network device
gre_mode Configuration method for device. Set to dynamic to have device configured by Controller. Set to static to have device configured using parameters in this config file.
[cert] Provides configuration parameters for the certificate.
cert_storage Full path to directory that stores certificate
key_length Key length in bytes
[rest] Provides configuration parameters for REST API
rest_ip IP Address of Agent’s REST interface
rest_port TCP port of Agent’s REST interface
log_file Full path to file used for logging REST records
log_level Defines loggin verbosity for REST API