Docs / Reference
Installer options
The installer is install/install.sh in the release. It sets up Gardience in one of two modes:
- All-in-one (the default): Gardience runs its own Salt master (Salt 3008.3), the console and the web front end.
- Attach mode (
--attach): Gardience connects to a Salt master you already run.
# all-in-one
sudo ./install/install.sh
# attach to your own Salt master
sudo ./install/install.sh --attach https://salt-master.example.com:8000 --eauth pam./install/install.sh --help prints the option list.
Before it starts
The installer stops with a message if:
- Docker is not installed, Docker Compose v2 (
docker compose) is missing, or Docker is not running or cannot be used by this user. opensslis not installed.- Gardience is already installed in the target directory. Manage that install with its
gardiencecommand. - Data from an earlier install with the same
--namestill exists in Docker. Install under that name and then restore a backup, or remove the old volumes first. The message gives the exact command. - It is an offline bundle built for a different processor type (amd64 or arm64) than this server.
Options
Location and naming
| Option | Default | Meaning |
|---|---|---|
--dir PATH | /opt/gardience as root, otherwise ~/gardience | Install directory. |
--name NAME | gardience-server | Docker Compose project name. Volume names start with it. Use the same name on both servers of a primary and standby pair. |
Console and certificate
| Option | Default | Meaning |
|---|---|---|
--https-port N | 443 | Port for the console. |
--http-port N | 80 | Port that redirects to HTTPS. |
--hostname NAME | This host's fully qualified name | Name in the TLS certificate and in the console address the installer prints. |
--tls-cert F | none | Your certificate. Give --tls-key with it. |
--tls-key F | none | The private key for --tls-cert. |
Without --tls-cert, the installer creates a self-signed certificate for --hostname, also valid for localhost and 127.0.0.1, lasting 825 days. You can replace it at any time.
Agents (all-in-one)
| Option | Default | Meaning |
|---|---|---|
--salt-bind IP | 0.0.0.0 | Address the Salt ports listen on. |
--salt-ports A,B | 4505,4506 | Salt publish and return ports. |
--master-address A | the --hostname value | Address agents use to reach this server. |
--fleet-size N | 500 | How many machines you expect to manage. Sizes the Salt master: worker threads, open file limit, connection backlog and key cache. |
Attach mode
| Option | Default | Meaning |
|---|---|---|
--attach URL | none | Turns on attach mode. URL of your salt-api. |
--eauth TYPE | file | Salt sign-in type for Gardience's service accounts on your master: pam, file or ldap. |
--insecure-salt-api | off | Accept a self-signed salt-api certificate. |
--attach-master-ip IP | none | The only address allowed to reach Gardience's internal endpoint (/gardience/internal/), which the Gardience modules on your master call, for example to fetch vault secrets. Without it, that endpoint is closed. |
--admins A,B | none | Users on your master who administer Gardience. Change later with gardience roles. |
--approvers A,B | none | Users who may approve runs. Admins approve too. |
In attach mode the installer also writes ATTACH.md and an attach-kit folder in the install directory. They list the steps to carry out on your Salt master. --admins and --approvers apply only in attach mode; on an all-in-one install roles come from gardience user add.
License and backups
| Option | Default | Meaning |
|---|---|---|
--license FILE | none | License file. Without one, the console is read-only. See Licensing. |
--backup-passphrase-file F | none | Encrypt the automatic pre-upgrade backups with this passphrase file. Recommended, because they hold every key. Keep the file off the backup's disk if you can. |
Warm standby
| Option | Default | Meaning |
|---|---|---|
--standby-address A | none | Agent address of the warm standby server. Agents are set up to fail over to it on their own. |
--peer-url URL | none | Console URL of the other server in a primary and standby pair. A returning old primary checks it and fences itself if the standby was promoted. gardience promote needs it. |
--witness-dir PATH | none | A folder on shared storage mounted on both servers of a pair. Promotions are recorded there, so a primary cut off from its partner still stops its Salt master. gardience promote refuses if it cannot write there. |
--peer-agent-address A | none | On the standby: the primary's agent address, so agents enrolled there after a promotion still list both servers. |
See High availability.
Used by upgrades
| Option | Meaning |
|---|---|
--upgrade | Used by gardience upgrade. Regenerates an existing install's compose file, web front end, Salt content and settings for this release, keeping its secrets, users, certificate, license and data. Do not run it by hand. |
Help
| Option | Meaning |
|---|---|
-h, --help | Print the option list and exit. |
Any other option stops the installer with "unknown option".
What the installer does
- Runs the checks above.
- Creates the install directory and copies in the Salt content (states, modules and a starter pillar).
- Generates random secrets: the service account passwords, the internal token, the single sign-on key and the runner token. They are written to
.env, readable by its owner only. - Creates or copies the TLS certificate.
- Writes the web server configuration and
compose.yml. - Builds the images, or loads them from an offline bundle without using the internet.
- On all-in-one installs, creates the
adminaccount and the two service accounts. - Starts Gardience and waits until
/gardience/healthanswers. - Prints the console address and, on all-in-one installs, the
adminpassword. It is shown once. Change it withgardience user passwd admin.