# Users and access parameters

Each key below carries a label for where it belongs in the configuration.
A [!badge variant="success" text="GUI"] key has a field in the interface; a
[!badge variant="warning" text="YAML only"] key is set in the
[Source (YAML) view](../../concepts/yaml-view.md), which accepts the same configuration.

## System users

A system user is the account that owns the files and runs the applications. Every
application belongs to exactly one system user.

**Example** - every key in this section, with realistic values:

```yaml
system_users:
  - username: prod
    vhosts:
      - server_name: example.com
        app_type: wordpress
```

### `system_users`

[!badge variant="secondary" text="host"] [!badge variant="info" text="list"] [!badge variant="success" text="GUI"]

Default `empty`.

The list of accounts on this host, each with its own applications. Separating applications per account keeps their files, databases and processes apart.

### `username`

[!badge variant="secondary" text="system user"] [!badge variant="info" text="string"] [!badge variant="success" text="GUI"]

The account name, which also determines the home directory and the database name. Required for every account.

**Note:** lowercase letters and digits, starting with a letter, at most 24 characters. Some reserved names are refused.

## File transfer accounts

File transfer accounts give someone access to files without giving them the system account
itself. Prefer Secure File Transfer Protocol (SFTP) over plain FTP.

**Example** - every key in this section, with realistic values:

```yaml
ftp_sftp: true             # use encrypted SFTP (host level)
ftp_sftp_port: 222
ftp_hostname: sftp.example.com
system_users:
  - username: prod
    ftp:
      - user: designer
        homedir: /var/www/prod/example.com   # must be inside the user's directory
```

### `ftp`

[!badge variant="secondary" text="system user"] [!badge variant="info" text="list"] [!badge variant="success" text="GUI"]

Default `empty`.

Extra file-transfer accounts under this system user. Give an external designer or agency access to one folder only.

### `user`

[!badge variant="secondary" text="system user"] [!badge variant="info" text="string"] [!badge variant="success" text="GUI"]

The login name of the file-transfer account. Required for every entry under `ftp`.

### `homedir`

[!badge variant="secondary" text="system user"] [!badge variant="info" text="string"] [!badge variant="success" text="GUI"]

The folder this account is limited to. Restricts access to one application instead of the whole account.

**Note:** must be inside the system user's own directory. The deployment fails otherwise.

### `ftp_sftp`

[!badge variant="secondary" text="host"] [!badge variant="info" text="boolean"] [!badge variant="success" text="GUI"] [!badge variant="danger" text="required"]

Default `false`.

Enables encrypted file transfer over SFTP. Plain FTP sends passwords unencrypted. Use SFTP whenever you can.

**Note:** required before you can add SSH keys to a file-transfer account, otherwise the deployment fails.

### `ftp_sftp_port`

[!badge variant="secondary" text="host"] [!badge variant="info" text="integer"] [!badge variant="secondary" text="port"] [!badge variant="warning" text="YAML only"] [!badge variant="ghost" text="advanced"]

Default `222`.

The port SFTP listens on. Avoids a clash with regular SSH.

### `ftp_hostname`

[!badge variant="secondary" text="host"] [!badge variant="info" text="string"] [!badge variant="success" text="GUI"] [!badge variant="ghost" text="advanced"]

The host name shown for file-transfer connections. Give customers a branded address to connect to.

## Extra database users

Extra database accounts. The `admin` role has full read/write access to all databases on the
server; the `readonly` role has read-only access.

**Example** - every key in this section, with realistic values:

```yaml
system_users:
  - username: prod
    db_extra_users:
      - name: reporting
        db_role: readonly       # admin | readonly
```

### `db_extra_users`

[!badge variant="secondary" text="system user"] [!badge variant="info" text="list"] [!badge variant="success" text="GUI"]

Default `empty`.

Additional database accounts alongside the automatically created one. Give a reporting tool or an external developer their own database login.

### `name`

[!badge variant="secondary" text="system user"] [!badge variant="info" text="string"] [!badge variant="success" text="GUI"]

The login name of the extra database user. Required for every entry under `db_extra_users`.

**Note:** lowercase letters and digits, starting with a letter, at most 24 characters, and unique.

### `db_role`

[!badge variant="secondary" text="system user"] [!badge variant="info" text="enum"] [!badge variant="success" text="GUI"] [!badge variant="danger" text="required"]

One of `admin`, `readonly`.

The role - `admin` has full read/write access to all databases on the server, `readonly` has read-only access. A reporting tool or external analyst should almost always be `readonly`; `admin` reaches every database on the server.

**Note:** required, and must be exactly one of the two values.

## SSH access

SSH gives command-line access to the server. Keys are safer than passwords, because a key
cannot be guessed.

**Example** - every key in this section, with realistic values:

```yaml
ssh_keys:
  - ssh-ed25519 AAAAC3Nza... team@example.com
ssh_passwords: false         # disable password login (keys only)
ssh_port: 22                 # YAML only; the firewall opens the new port for you
```

### `ssh_keys`

[!badge variant="secondary" text="host"] [!badge variant="info" text="list"] [!badge variant="success" text="GUI"]

Default `empty`.

Public keys that get access to every account on this host. Give your whole team access in one place, without sharing passwords.

### `ssh_port`

[!badge variant="secondary" text="host"] [!badge variant="info" text="integer"] [!badge variant="secondary" text="port"] [!badge variant="warning" text="YAML only"]

Default `22`.

The port the server listens on for SSH. A non-standard port removes most automated login attempts from your logs.

> [!WARNING]
> Set the wrong value and you lock yourself out. The firewall is opened for the new port automatically.

### `ssh_passwords`

[!badge variant="secondary" text="host"] [!badge variant="info" text="boolean"] [!badge variant="success" text="GUI"]

Default `true`.

Whether logging in with a password is allowed at all. Turning it off is one of the most effective hardening steps, because passwords can be guessed.

**Note:** add and test your SSH key first.

## Related

- [YAML configuration reference](index.md)
- [The Source (YAML) view](../../concepts/yaml-view.md)
- [Publishing changes](../../platform/hosts/publishing.md)