diff --git a/Inventory-Scope.md b/Inventory-Scope.md index f524a8a..80f6ff4 100644 --- a/Inventory-Scope.md +++ b/Inventory-Scope.md @@ -29,7 +29,7 @@ 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 value particular data types: +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 ---|---|--- @@ -58,7 +58,7 @@ vps_service: - "sk-ecdsa-sha2-nistp256@openssh.com AAASAgsflgkjzldoijrta[hjwe[hafWRYASFHzdmvgjheaaWRAFGHn== anon@device" root_fate: "disposal" ssh_private_key_paths: - -" ${HOME}/.ssh/id_ecdsa-vps.ppk" + - "${HOME}/.ssh/id_ecdsa-vps.ppk" ssh_private_key_path_pref: 0 ssh_motd_script_basenames: - "00-logo.sh" @@ -67,11 +67,193 @@ vps_service: ## `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: + +```yaml +# $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` | `:}>` | 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` | `` | determines the group name actually used on creation of the group +`type` | `` | determines the type of user a group is for (e.g., Linux's system users v. regular users) +`id` | `` | 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: + +```yaml +# $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` | `:}>` | 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` | `` | determines the username actually used on creation of the user account +`id` | `` | determines the user ID for this user account +`password` | `` | determines the login or "sudoer" password for this user account +`shell` | `` (path) | determines the shell spawned on login to this user account +`home` | `` (path) | determines the directory owned by this user account that is the initial present working directory on login +`admin` | `` | determines whether this user account should be treated as the future administrative count of the remote server by Ansible +`type` | `` | determines whether this user account is "regular" (a regular user) or "system" (a system user) +`group` | `` | determines the primary group of this user account +`groups` | `]>` (each item is a group [name]) | determines the supplementary groups this user account will be in +`services` | `]>` (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` | `]>` (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` | `]>` (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` | `` (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` | `]>` (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` | `` (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` | `` (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: + +```yaml +# $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` -> **TBC** -> This Wiki page remains unfinished. Check back later. \ No newline at end of file +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: + +```yaml +# $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 +``` \ No newline at end of file