Version: Next

Deploying a Master-server

Integrating an existing Salt Master server with Salt.Box

This instruction is intended for users who want to connect an existing Salt Master server to the deployed Salt.Box software suite.

note

It is assumed that Salt.Box is deployed in Docker application containerizer as per the online documentation section "Deploying Salt.Box Server".

Prerequisites

Salt Master server (host with the SaltStack server component installed from the official repository - the salt-master package version 3006.9 or higher).
Salt.Box server with access to its Redis instance from the local network.

Checking the availability of the Redis server

It is recommended to check the availability of the Redis server on the Salt.Box server before integration.

Perform a connection test to the Redis server (to the TCP/6379 port) from the Salt.Box server's command shell:

nc -vz <IP_or_HOSTNAME_of_Salt_Box> 6379

Make sure that the command output does not contain any error messages, such as "Connection refused", "No route to host", etc.

On the Salt Master server, run:

git clone https://dev.saltbox.pro/salt.box/salt-box-bridge.git

On the Salt.Box server, run:
```
sudo docker compose cp redis-salt:/etc/redis/certs/ca.crt ./redis-ca.crt
```
Copy the redis-ca.crt file to the /etc/salt/ssl/ directory of the Salt Master server.

On the Salt Master server, execute the following commands in sequence:

sudo mkdir -p /srv/salt_extmod/engines
sudo mkdir -p /srv/salt_extmod/runners
sudo mkdir -p /etc/salt/salt_box.d
sudo mkdir -p /etc/salt/ssl

Copy all files with the .py extension from the engines/ and runners/ directories of the salt-box-bridge repository to the corresponding directories on the Salt Master server:
- engines/ → /srv/salt_extmod/engines/
- runners/ → /srv/salt_extmod/runners/
Make sure the files are owned by the root user.
Install the salt_box_bridge_service module using the pip utility corresponding to the Python version of your Salt Master server:
```
sudo /opt/saltstack/salt/bin/pip3.10 install /path/to/salt-box-bridge/salt_box_bridge_service
```

Create a file /etc/salt/master.d/master.conf with the following contents:

salt_master_id: UNIQUE_NAME       # Unique Salt Master server identifier

module_dirs:
  - /srv/salt_extmod/             # Path to directories with custom modules (engines and runners)

auto_accept: true                 # Automatically accept minion keys

presence_events: True             # Sending minion presence events

engines:
  - salt_box_redis_bridge:        # Engine for interaction via Redis
      salt_box_env_file: '/etc/salt/salt_box.d/.env'
  - salt_box_service:             # Engine for registering a master in SaltBox
      salt_box_env_file: '/etc/salt/salt_box.d/.env'

schedule:
  salt_box_redis_bridge_cleanup:  # Periodic clean up stale tasks in Redis
    hours: 3
    function: salt_box_redis_bridge.cleanup_expired_jobs
    kwargs:
      expire: 604800              # The lifetime of a task before it is cleaned up
      redis_host: redis-salt      # Redis host (may be left as is if configured via .env)

Create a file /etc/salt/salt_box.d/.env with the following contents:

REDIS_HOST="Salt_Box_IP_or_hostname" # IP address or hostname where Salt.Box and Redis are installed
REDIS_USERNAME="Redis_user"     # Redis username (REDIS_SALT_USERNAME variable on Salt.Box server)
REDIS_PASSWORD="Redis_password" # Redis user password (from the file 'secrets/redis_salt_password')

REDIS_SSL_USE=True              # Whether to use TLS connection to Redis
REDIS_SSL_CA_CERTS="/etc/salt/ssl/redis-ca.crt" # Path to Redis CA certificate obtained from Salt.Box

EXPIRE=604800                   # Redis command lifetime (in seconds)
MASTER_SECRET="Unique_secret"   # Master's unique secret key (can be generated by pwgen)

note

Make sure the variable values match your Salt.Box server settings.

Generate a unique Master Server ID

info
This step is optional.

Run this script to generate a unique identifier:
```
./make_master_id.sh > /etc/salt/salt_box.d/master_id.txt
```
Then specify the file with the unique identifier in the master.conf file:
```
salt_master_id: /etc/salt/salt_box.d/master_id.txt
```
Apply the changes by restarting the salt-master service:
```
sudo systemctl restart salt-master.service
```

After completing all the steps, your Salt Master server will be integrated with Salt.Box and will be able to interact with the latter's components via the Redis server.

Integrating an existing Salt Master server with Salt.Box​

Prerequisites​

Checking the availability of the Redis server​

Integrating an existing Salt Master server with Salt.Box

Prerequisites

Checking the availability of the Redis server