This article describes what you can check if there is reason to believe that the Master cannot communicate with a Server Agent. Evidence of this can be for example if new user accounts or password updates do not reach the Agent.

Another symptom can be if the Agent does not seem to contact the Master (or Replica); For example, if the Server Agent host refuses logins that should work or, again, if new user accounts, groups and password updates etc. do not reach the Agent.

Resolution / Workaround

Follow these steps to troubleshoot communication:

First check the port numbers:

By default BoKS uses a port range starting with 6500, but this is configurable in /etc/services, so run the following on both the Master and the Server Agent:

grep boks /etc/services

If boks is found, make sure it is using the same port or edit the files.

Now check the Master to Server Agent connection from the Master:

First, run:

checkdomain -h

checkdomain will start by pinging the Agent and if that fails, this will show in the output. If it fails you should check the network and firewalls from the Master to the Server Agent. Also see 'Checking port' below.

If checkdomain shows that communication is ok, but says that 'BoKS is not running' there, you should check the port, hostkey, and communication encryption.

Checking port:

If the base port in /etc/services is 6500 (default base port) the Master needs to be able to contact the Server Agent with TCP on baseport+3, that is 6503, so make sure firewalls allow this.

To verify that the port can be reached on the Agent, you can telnet from the Master to the Agent on port 6503 and while not being able to login, at least see that there is a connection established.

Checking hostkey: (used for BoKS internal communication)

In the $BOKS_var/boks_errlog there might be errors such as "Cannot encrypt message" which indicate a problem with the hostkey.

On the Master, run:

hostkey -g -h

On the Agent, run:


and make sure that they are the same. (Only hashes are shown, not the actual key).

On BoKS v6.5 as compared to BoKS v6.6 and later, the host keys have different lengths, so if one of the key hashes listed above is longer, only compare the first half with the shorter key (and check encryption below).

Here is how to set new host keys if necessary:

On the Master:

hostkey -s -h

On the Agent:

hostkey -f

Checking communication encryption:

BoKS v. 6.5, as compared to v. 6.6 and later, uses different encryption for BoKS communication by default. BoKS v. 6.5 uses RC5-128 and v. 6.6 and later uses AES-256.

Default encryption for a host can be set with the variable BRIDGE_CRYPT in the local $BOKS_etc/ENV file.

You can set it with for example:


or alternatively CRYPT_AES_256, but RC5-128 is the highest BoKS v. 6.5 can go.

Note that you must restart BoKS processes on the Server Agent if you have changed this parameter:


This should be enough on an Agent where the Master and all Replicas run the same encryption.

On the Master you may have to set different encryption for different Server Agents, so then you must create and configure the BOKS_etc/bremotever file. See the bremotever manual page for how to do that.

If a BoKS v. 6.5 host tries to contact a v. 6.6 host there may be errors about "Unknown bridge protocol" in $BOKS_var/boks_errlog due to v. 6.6 (or later) using AES-256.


If you have set BRIDGE_CRYPT=CRYPT_RC5_128 on the Master and Replicas in order to support BoKS 6.5 clients, it is not necessary to have this parameter in the ENV file on BoKS 6.6 and later Server Agents. In this scenario (and without explicit specification in the $BOKS_etc/bremotever file) the BoKS Master will encrypt messages with RC5-128 and the 6.6 and later Server Agents will respond with messages encrypted with AES-256. Both ends are able to decrypt as they are capable of handling both encryption algorithms.

Checking Server Agent to Master and Replica connection from the Server Agent:

First, run:

showmaster -s

This will tell you if the Master or one of the Replicas is able to respond to a UDP message on port 6501 (assuming base port set to 6500). If not, you have to check firewalls so that the Server Agent can reach the Master and Replicas on port 6501 with both TCP and UDP.

If the Server Agent is on a different subnet, a broadcast message will not reach the Master and Replicas. In that case you will have to create the $BOKS_etc/bcastaddr file. See the bcastaddr manual page.

You can verify the TCP connection by connecting to the Master or a Replica with telnet on port 6501 - while you will not be able to log in, at least you will be able to see that there is a connection established.

The BRIDGE_ADDR_USE ENV-file parameter

When a Server Agent connects to a BoKS server, it will pass one of its IP addresses in the negotiation. That address is not necessarily the same as used by the connection, but has to match one of the addresses registered in BoKS.

Thus, if not all addresses have been registered in BoKS database, you must set the BRIDGE_ADDR_USE variable in the local $BOKS_etc/ENV file on the Server Agent to one of the registered IP addresses. You can do that by editing $BOKS_etc/ENV locally or using the cadm command.

For example to use cadm locally on the Server Agent:


Note that you must restart BoKS processes on the Server Agent if you have changed this parameter:


An alternative is to register all IP addresses a host uses in the BoKS database. To add another IP address to a host use:

hostadm -a -h -i

Also check hostkey and encryption as above.

About Replicas

As far as the Server Agent is concerned, the Master is yet another Replica. Running

showmaster -s

will show the first Master or Replica to respond, but will not show if all of them could be contacted.

Connection from a Server Agent to any Replica works the same as the Master concerning port, bcastaddr, hostkey, encryption etc., so TCP connection can be verified with telnet as mentioned above.

Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: June 28, 2019