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
- default installation dir =
There are two ways to run the configuration script
- 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 inib_agent.conf
are used.
- 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 inib_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 |