Inventory Scope

Herein the variables at or in the inventory scope are explained further. We already have the following table from the overview:

name	type	value validity rule
`fqdn`	`<str>`	fully qualified domain name
`vps_service`	`<dict{<str>:<str\|bool\|list>}>`	valid fields providing data for spinning up new VPS
`groups`	`<dict{$group_name:<dict>}>`	fields/keys that are group names with data configuring that group
`users`	`<dict{$user_name:<dict>}>`	fields/keys that are user names with data configuring that user
`keywords`	`<list[<str>]>`	strings that describe the VPS, useful for applying tags if allowed by API
`custom_vars`	`<dict{<str>:<any>}>`	your own custom variables, though there are some reserved variable names for this namespace

Note

These variables should be defined either per host or per group, as they may be distinct for each host/group. Consequently, it is preferable to to define these variables in files under $SKATO_ANSIBLE_ROOT/group_vars or $SKATO_ANSIBLE/host_vars, each file having the name of the relevant inventory host or group.

`fqdn`

The fqdn variable, whose name is the acronym for Fully Qualified Domain Name, takes in exactly that as its value: a fully qualified domain name (as a <str> data type). This is essentially the domain name associated to the public IP address of your Virtual Private Server, or that you entered into a DNS record pointing to the public IP address of that Virtual Private Server. For example, sukaato.moe would be the relative top-level domain for the server this Gitea instance is on, git.sukaato.moe being a subdomain.

Here is an example:

# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
fqdn: "sukaato.moe"

`vps_service`

The vps_service takes in a dictionary data type as value, that itself has the following fields or keys that have as values particular data types:

key	value type	purpose
`exists`	`<bool>`	determines whether the VPS is to be created
`password`	`<str>`	the password to be given to the intiial root user
`api_key`	`<str>`	the API key to take control of your account in order to create the VPS
`type`	`<str>`	the name or ID of the VPS service being used (so far, only "linode" is possible to use)
`region`	`<str>`	the geographical region the VPS will be spawned in / make connections from--must follow the convention established by the VPS service
`ssh_authorized_keys`	`<list[<str>]>` (each item is the content of a public key file)	determines the public keys that that are authorized to access the VPS as `root`
`root_fate`	`<str>`	if the string states "disposal," this means we do not want to retain SSH or login access to the root account after some necessary initial set-up
`ssh_private_key_paths`	`<list[<str>]>`	determines the private keys on local machine to be used to access the VPS via SSH as `root`
`ssh_motd_script_basenames`	`<list[<str>]>` (each item is a basename of a bash script file in `$SKATO_ANSIBLE_ROOT/roles/bootstrap/files/update-motd.d`)	determines which script files in the aforementioned path are used for SSH MOTD
`ssh_private_key_path_pref`	`<int>` (corresponds to an index of `ssh_private_key_paths`, so must be less than `len(ssh_private_key_paths)`)	determines the default private key file used to access VPS via SSH as `root`

Here is an example:

# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
vps_service:
  exists: true
  password: "password123"
  api_key: "sajhnglajgknjwfjioAJGGJP"
  type: "linode"
  region: "us-east"
  ssh_authorized_keys:
    - "sk-ecdsa-sha2-nistp256@openssh.com AAASAgsflgkjzldoijrta[hjwe[hafWRYASFHzdmvgjheaaWRAFGHn== anon@device"
  root_fate: "disposal"
  ssh_private_key_paths:
    - "${HOME}/.ssh/id_ecdsa-vps.ppk"
  ssh_private_key_path_pref: 0
  ssh_motd_script_basenames:
    - "00-logo.sh"
    - "01-data.sh"

`keywords`

The keywords is simply a list of items or elements that are string data types, each item or element a descriptive tag of or for the intended VPS.

Here is an example:

# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
keywords:
  -  web
  - cloud
  - ftp

`groups`

The groups variable takes in a dictionary data type as value, that itself has the following fields or keys that have as values particular data types:

key	value type	purpose
`$group_name`	`<dict{<str>:<str\|int>}>`	specifies the group to be created

$group_name is the name of a given group as a key or field, for purposes of reference in Ansible. The dictionary value of this key/field must itself contain the following keys/fields:

key	value type	purpose
`group_name`	`<str>`	determines the group name actually used on creation of the group
`type`	`<str>`	determines the type of user a group is for (e.g., Linux's system users v. regular users)
`id`	`<int>`	determines the group's group ID

As an example, we have this required entry for a group that determines what users on the system will remain SSH-accessible:

# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
groups:
  remote:
    group_name: "remote"
    type: "system"
    id: ~

Note

As can be noted in the above example, id field/key is not strictly necessary.

`users`

The users variable takes in a dictionary data type as value, that itself has the following fields or keys that have as values particular data types:

key	value type	purpose
`$user_name`	`<dict{<str>:<str\|int\|list\|dict>}>`	specifies the user to be created

$user_name is the name of a given group as a key or field, for purposes of reference in Ansible. The dictionary value of this key/field must itself contain the following keys/fields:

key	value type	purpose
`username`	`<str>`	determines the username actually used on creation of the user account
`id`	`<int>`	determines the user ID for this user account
`password`	`<str>`	determines the login or "sudoer" password for this user account
`shell`	`<str>` (path)	determines the shell spawned on login to this user account
`home`	`<str>` (path)	determines the directory owned by this user account that is the initial present working directory on login
`admin`	`<bool>`	determines whether this user account should be treated as the future administrative count of the remote server by Ansible
`type`	`<str>`	determines whether this user account is "regular" (a regular user) or "system" (a system user)
`group`	`<str>`	determines the primary group of this user account
`groups`	`<list[<str>]>` (each item is a group [name])	determines the supplementary groups this user account will be in
`services`	`<list[<str>]>` (each item is a valid service name)	determines the services this user account is expected to own and manage on the VPS
`ssh_authorized_keys`	`<list[<str>]>` (each item is the contents of an SSH public key)	determines what public keys will allow access to this user account on the VPS via SSH
`ssh_private_key_paths`	`<list[<str>]>` (each item is a path on the local machine to an SSH private/secret key)	determines what private/secret SSH keys can be used from local machine for Ansible access to this user account on the VPS via SSH
`ssh_private_key_path`	`<int>` (an index of `ssh_private_key_paths`, such that it is less than `len(ssh_private_key_paths)`)	determines which key in `ssh_private_key_paths` is to be used by Ansible to access this user account on the VPS via SSH
`gpg_keys`	`<list[<dict>]>` (each item is a dictionary with fields/keys `id`, `name`, and `password`)	determines what GPG keys are to be imported for this user account on the VPS
`gpg_keyid_pref`	`<int>` (an index of `gpg_keys`, such that it is less than `len(gpg_keys)`)	determines the default GPG key to be used by this user account
`git_profile`	`<dict>` (contains fields/keys `name` and `email`)	specifies user account- specific git configuration arguments

It is required that there be at least one administrative user account specified, with the username key as "senpai", with at least "sshd" in its services list. It is also required that there be another user of key "ftp" with at least "sftp" in its services list, for (s)FTP services. It is highly recommended, however, to also add "proftpd" and "ftps" to that list. Both of these required user accounts must be part of the required supplementary group of key "remote," while only the administrative user account of key "senpai" must also be part of the required supplementary group "sudo".

Important

It is strongly recommended that all users have a specified ID.

These required accounts can serve as examples of how users are written:

# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
users:
  senpai:
    username: "admin"
    id: 1000
    password: "password123"
    shell: ~ # @NOTE a null value will have the default shell used instead
    home: ~ # @NOTE a null value will have a default `/home` subdirectory created/assigned instead
    admin: true
    type: regular
    group: ~ # @NOTE a null value will have the primary group be the default, which is a created group whose name is the username of this user
    groups:
      - "sudo" # @NOTE since this is an administrative account, the user must be in the superuser group
      - "{{ group['remote']['group_name'] }}" # @NOTE user account *MUST* be in this supplementary group to allow SSH access 
    services: ["sshd"]
    ssh_authorized_keys:
      - "sk-ecdsa-sha2-nistp256@openssh.com olAIRPALOJRFOLGAlajnlGLNHlikhnaflgn== anon@device"
    ssh_private_key_paths:
      - "${HOME}/.ssh/id_ecdsa-vps-2.ppk"
    ssh_private_key_path_pref: 0
    # @NOTE below only needed for regular / non-system user accounts
    gpg_keys:
      - id: "445C326F5A66"
        name: "admin@fq.dn"
        password: "justanotherpassword67"
    gpg_keyid_pref: 0
    # @NOTE below only needed for regular / non-system user accounts
    git_profile:
      name: "Jane Doe"
      email: "admin@fq.dn"
  ftp:
    username: "ftp"
    id: 999
    password: ~
    shell: "/sbin/nologin"
    home: "/srv/ftp"
    admin: false
    type: "system"
    group: ~
    groups:
      - "{{ groups.remote.group_name }}"
    services: ["proftpd","sftp","ftps"]
    # @NOTE below two field/key values needed to support SFTP service, if included in previous "services" key/field
    ssh_authorized_keys:
      - "sk-ecdsa-sha2-nistp256@openssh.com olAIRPALOJRFOLGAlajnlGLNHlikhnaflgn== anon@device"
    ssh_private_key_paths:
      - "${HOME}/.ssh/id_ecdsa-vps-2.ppk"
    ssh_private_key_path_pref: 0
    gpg_keys: [] # @NOTE not necessary for a mere system account
    gpg_keyid_pref: 0 # @NOTE not necessary for a mere system account
    git_profile: ~  # @NOTE not necessary for a mere system account

`custom_vars`

The custom_vars variable is meant to create a shared namespace for any additional variables one wants to define, that can't be defined as key-value pairs elsewhere. For example, because our two users specified in the example of the previous section share the same authorized public keys and private key authentication, we could just define those under this variable, and then reference these definitions under the relevant fields/keys of each user:

# $SKATO_ANSIBLE_ROOT/host_vars/sukaato.moe
custom_vars:
  shared:
    ssh_authorized_keys:
    ssh_private_key_paths:
    
users:
  senpai:
    username: "admin"
    id: 1000
    password: "password123"
    shell: ~ # @NOTE a null value will have the default shell used instead
    home: ~ # @NOTE a null value will have a default `/home` subdirectory created/assigned instead
    admin: true
    type: regular
    group: ~ # @NOTE a null value will have the primary group be the default, which is a created group whose name is the username of this user
    groups:
      - "sudo" # @NOTE since this is an administrative account, the user must be in the superuser group
      - "{{ group.remote.group_name }}" # @NOTE user account *MUST* be in this supplementary group to allow SSH access 
    services: ["sshd"]
    ssh_authorized_keys: "{{ custom_vars['shared']['ssh_authorized_keys'] }}"
    ssh_private_key_paths: "{{ custom_vars['shared']['ssh_private_key_paths'] }}"
    ssh_private_key_path_pref: 0
    # @NOTE below only needed for regular / non-system user accounts
    gpg_keys:
      - id: "445C326F5A66"
        name: "admin@fq.dn"
        password: "justanotherpassword67"
    gpg_keyid_pref: 0
    # @NOTE below only needed for regular / non-system user accounts
    git_profile:
      name: "Jane Doe"
      email: "admin@fq.dn"
  ftp:
    username: "ftp"
    id: 999
    password: ~
    shell: "/sbin/nologin"
    home: "/srv/ftp"
    admin: false
    type: "system"
    group: ~
    groups:
      - "{{ groups.remote.group_name }}"
    services: ["proftpd","sftp","ftps"]
    # @NOTE below two field/key values needed to support SFTP service, if included in previous "services" key/field
    ssh_authorized_keys: "{{ custom_vars['shared']['ssh_authorized_keys'] }}"
    ssh_private_key_paths: "{{ custom_vars['shared']['ssh_private_key_paths'] }}"
    ssh_private_key_path_pref: 0
    gpg_keys: [] # @NOTE not necessary for a mere system account
    gpg_keyid_pref: 0 # @NOTE not necessary for a mere system account
    git_profile: ~  # @NOTE not necessary for a mere system account