Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wikioasis/salt/llms.txt

Use this file to discover all available pages before exploring further.

Every server in the WikiOasis farm is managed by Salt from first boot. This runbook walks through the complete process — from installing the minion agent to verifying that all role-appropriate states have been applied cleanly. Follow each step in order; the minion’s ID is especially important because it controls which states and pillar data are automatically assigned.

​
Naming convention and role assignment

The minion ID you choose at provisioning time is the primary key Salt uses to determine every role and pillar assignment. Both salt/top.sls and pillar/top.sls use glob patterns matched against the minion ID, so getting the name right is critical before you ever run a state.
Minion ID patternStates applied
mw*mediawiki.target, php, nginx, sentry_relay, monitoring.nrpe_nginx, monitoring.nrpe_php, monitoring.nrpe_mediawiki, monitoring.phpfpm_exporter
staging*mediawiki, php, nginx, sentry_relay, monitoring.nrpe_nginx, monitoring.nrpe_php, monitoring.nrpe_mediawiki, monitoring.phpfpm_exporter
task*php, nginx, mediawiki.target, mediawiki.jobrunner, monitoring.nrpe_nginx, monitoring.nrpe_php, monitoring.phpfpm_exporter
apps*php, nginx, monitoring.nrpe_nginx, monitoring.nrpe_php, monitoring.phpfpm_exporter
db*mariadb, mariadb.monitoring_user, mariadb.prometheus_user, mariadb.backup, mariadb.nrpe_backup, monitoring.mysqld_exporter
proxy*haproxy, mediawiki.proxy, monitoring.nrpe_haproxy, monitoring.haproxy_exporter
redis*redis, monitoring.nrpe_redis, monitoring.redis_exporter
opensearch*opensearch, monitoring.nrpe_opensearch, monitoring.opensearch_exporter
monitoring*monitoring, monitoring.director, monitoring.nrpe_nginx, monitoring.prometheus, monitoring.grafana, monitoring.statsd_exporter
metal*metal, monitoring.nrpe_metal
salt*monitoring.nrpe_salt_master
Every minion also inherits the universal base, users, monitoring.nrpe, monitoring.nrpe_common, monitoring.nrpe_salt, and monitoring.node_exporter states regardless of its name.
The mw* and staging* patterns both match the compound rule mw* or staging* in salt/top.sls, which applies php, nginx, sentry_relay, and the associated monitoring states. The mw* pattern additionally receives mediawiki.target; the staging* pattern additionally receives mediawiki.All servers whose IDs match *-us-east-0[0-9][0-9]* also receive the metal.vm_ipv6 state, which configures IPv6 addressing for virtual machines hosted on bare-metal hypervisors.

​
Adding the server

1

Provision the server

Boot the new machine from a Debian image. Once the OS is running, install the Salt minion package and point it at the Salt master:
apt-get install -y salt-minion
Edit /etc/salt/minion and set the master address and the minion ID you have chosen:
master: salt-master.wikioasis.org
id: mw-us-east-031
Then enable and start the service:
systemctl enable --now salt-minion
The minion will generate an RSA key pair and send its public key to the master for acceptance.
2

Accept the minion key on the master

On the Salt master, list pending keys and accept the new minion:
# List unaccepted keys
salt-key -L

# Accept the specific minion
salt-key -a mw-us-east-031
Verify connectivity immediately after accepting:
salt 'mw-us-east-031' test.ping
You should receive True within a few seconds.
Never accept a key you did not expect. If unfamiliar keys appear, investigate before accepting — any accepted minion can receive pillar data including secrets.
3

Add per-host pillar data if required

Some roles need per-host pillar files. Database servers are the most common example — each db-* host has its own .sls file in pillar/mariadb/ that sets connection parameters, backup credentials, and tuning values.Check pillar/top.sls to see whether a new entry is needed for your minion ID:
# pillar/top.sls (excerpt)
'db-c1-us-east-021*':
  - mariadb.db-c1-us-east-021
If your new server needs dedicated pillar data, create the file (e.g. pillar/mariadb/db-c2-us-east-031.sls) and add the matching glob to pillar/top.sls:
'db-c2-us-east-031*':
  - mariadb.db-c2-us-east-031
Similarly, per-host Redis pillar files live under pillar/redis/ and are referenced by their own glob patterns:
'redis-us-east-011*':
  - redis.redis-us-east-011
The private pillar must be present on the master before applying any state that references secrets (passwords, SSH keys, API tokens). Confirm with your team that the private pillar has been updated for the new host.
4

Verify pillar data

Before applying any state, confirm the minion sees the correct pillar values. This catches missing private pillar files or top.sls mismatches early:
salt 'mw-us-east-031' pillar.items
For a database server, also confirm the MariaDB-specific keys are populated:
salt 'db-c2-us-east-031' pillar.get mariadb
If the output is empty or missing expected keys, fix the pillar before proceeding.
5

Apply the base state

The base state configures system-wide settings (timezone, APT mirror) and is safe to apply to any server at any time. Apply it first to establish a known baseline:
salt 'mw-us-east-031' state.apply base
The users state is applied automatically as part of the top file for all minions, but you can apply it explicitly if needed:
salt 'mw-us-east-031' state.apply users
6

Apply the role states

Apply the states that correspond to the server’s role. Use state.highstate to apply everything from top.sls at once, or apply individual states if you want to bring the server up incrementally.MediaWiki application server:
salt 'mw-us-east-031' state.highstate
Database server:
salt 'db-c2-us-east-031' state.apply mariadb
salt 'db-c2-us-east-031' state.apply mariadb.backup
HAProxy load balancer:
salt 'proxy-us-east-031' state.apply haproxy
salt 'proxy-us-east-031' state.apply mediawiki.proxy
Redis cache server:
salt 'redis-us-east-031' state.apply redis
OpenSearch node:
salt 'opensearch-us-east-031' state.apply opensearch
Monitoring server:
salt 'monitoring-us-east-031' state.highstate
Run with test=True first on any production server to preview the changes that will be made without applying them:
salt 'mw-us-east-031' state.highstate test=True
7

Verify the server is healthy

After states apply cleanly, confirm the server is reachable and monitored:
# Connectivity
salt 'mw-us-east-031' test.ping

# Check service status (example: nginx on a MediaWiki server)
salt 'mw-us-east-031' service.status nginx

# Verify all applied states report no failures
salt 'mw-us-east-031' state.highstate test=True
Log into Icinga2 and confirm the new host appears and all service checks are passing. If the host does not appear within a few minutes, check that the monitoring.director state has been applied to the monitoring server and that monitoring:icinga_api_host is set correctly in the private pillar.

​
Reference: pillar/top.sls glob patterns

The table below summarises the per-role pillar assignments from pillar/top.sls. These are applied on top of the universal base, users, and private pillars that every minion receives.
PatternPillar files
db*mariadb, private
db-other-us-east-011*mariadb.db-other-us-east-011
db-pc-us-east-011*mariadb.db-pc-us-east-011
db-c1-us-east-021*mariadb.db-c1-us-east-021
mw* or staging*users.servers.mediawiki, php, nginx, mediawiki
proxy*haproxy, mediawiki
redis-us-east-011*redis.redis-us-east-011
redis-us-east-012*redis.redis-us-east-012
monitoring*monitoring, metal, private
apps*php, private
task*users.servers.mediawiki, php, nginx, mediawiki, mediawiki.jobrunner
bastion*users.servers.bastion
metal-us-east-01*metal.metal-us-east-01
metal-us-east-02*metal.metal-us-east-02

Maintenance Runbook

Learn how to depool, schedule downtime, apply configuration changes, and repool a server safely.

Database Backup

Understand the full, incremental, and binlog streaming backup system for MariaDB servers.

Build docs developers (and LLMs) love

Get started for freeTalk to us