diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..3d54409 --- /dev/null +++ b/lychee.toml @@ -0,0 +1,19 @@ +# More info: https://lychee.cli.rs/usage/config/ +verbose = "info" +cache = true +require_https = false +include_verbatim = true +exclude_private = true +exclude_link_local = true + +# Remap URI matching pattern to different URI. +# remap = ["https://example.com http://example.invalid"] +remap = [ + "https://copr-be.cloud.fedoraproject.org/results/thm https://copr-be.cloud.fedoraproject.org/results/thm/lxc", + "https://rpms.remirepo.net https://rpms.remirepo.net/%7B%", + "https://dl.fedoraproject.org/pub/epel https://dl.fedoraproject.org/pub/epel/epel-release-latest-" +] +# Exclude URLs and mail addresses from checking (supports regex). +# exclude = ['^https://www\.linkedin\.com', '^https://web\.archive\.org/web/'] +exclude = ['^http://localhost', '^http://your.zabbix.domain'] + diff --git a/roles/bareos/.ansible-lint b/roles/bareos/.ansible-lint index 9d5968a..e1f738c 100644 --- a/roles/bareos/.ansible-lint +++ b/roles/bareos/.ansible-lint @@ -1,17 +1,12 @@ --- -### ansible linter config -### -### more details: -### - https://ansible-lint.readthedocs.io/en/latest/configuring/#configuration-file -### Please keep in mind how to skip rule inside a playbook/role: -### - https://ansible-lint.readthedocs.io/en/latest/rules/#false-positives-skipping-rules +# ansible-lint config +# see: https://ansible.readthedocs.io/projects/lint/usage/#specifying-rules-at-runtime +# https://ansible.readthedocs.io/projects/lint/usage/#muting-warnings-to-avoid-false-positives -exclude_paths: - - .gitignore - - .gitmodules quiet: true verbosity: 1 +# exclude_paths: # skip_list: # enable_list: # warn_list: diff --git a/roles/bareos/.gitkeep b/roles/bareos/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/roles/bareos/.yamllint b/roles/bareos/.yamllint index b45b2f6..08631a5 100644 --- a/roles/bareos/.yamllint +++ b/roles/bareos/.yamllint @@ -7,7 +7,10 @@ ignore: | rules: braces: + min-spaces-inside: 0 max-spaces-inside: 1 + min-spaces-inside-empty: 0 + max-spaces-inside-empty: 0 level: error brackets: max-spaces-inside: 1 @@ -20,7 +23,7 @@ rules: level: error comments: disable comments-indentation: disable - document-start: disable + document-start: enable empty-lines: max: 2 level: error @@ -37,4 +40,4 @@ rules: trailing-spaces: enable truthy: allowed-values: ['true', 'false'] - check-keys: true + check-keys: true \ No newline at end of file diff --git a/roles/bareos/README.md b/roles/bareos/README.md index f8148df..7917453 100644 --- a/roles/bareos/README.md +++ b/roles/bareos/README.md @@ -1,9 +1,9 @@ -bareos -====== +# bareos + This role installs and configures [Bareos](https://www.bareos.com/) and required third-party components. -Specification -------------- +## Specification + Normally this role is for the next cases: - Typical installation of Bareos director using PostgreSQL, Bareos Web UI using Apache, Bareos storage and Bareos @@ -57,24 +57,25 @@ on Debian, so use external or manual iptables control. - TLS certificates and setting not supported in this role, but you can copy all required files setting up [`bareos_configs_to_copy` variable](#role-variables). -Requirements ------------- +## Requirements + - Any version of Ubuntu or any Debian family distribution, any RedHat family distribution or any Alpine Linux (but -please check `override_ansible_distribution_major_version` [role variable description](#main-role-variables) first). + please check `override_ansible_distribution_major_version` [role variable description](#main-role-variables) first). + +## Dependencies -Dependencies ------------- - PostgreSQL which can be installed using this role or not. - [python-psycopg](https://www.psycopg.org/) is not required for Bareos, but will be installed together with PostgreSQL. - Apache2 web server and Epel repo (for `libzstd` package download on CentOS) which will be automatically installed -running this role. + running this role. - This role using 'sudo' become method, so Debian distribution should have them already pre-installed. - Alpine Linux binaries built unofficially they could have some bugs -([like this one](https://gitlab.alpinelinux.org/alpine/aports/-/issues/14570)). Before you run this role on Alpine Linux -set your `/etc/apk/repositories` manually (read [documentation](https://wiki.alpinelinux.org/wiki/Repositories)). + ([like this one](https://gitlab.alpinelinux.org/alpine/aports/-/issues/14570)). Before you run this role on Alpine + Linux set your `/etc/apk/repositories` manually (read + [documentation](https://wiki.alpinelinux.org/wiki/Repositories)). + +## Example Playbooks -Example Playbooks ------------------ The easiest ways to use this role should look like typical installation: [all Bareos components](https://docs.bareos.org/IntroductionAndTutorial/InstallingBareosWebui.html#installation) on the same host and/or @@ -88,147 +89,164 @@ In another hand, you can install or uninstall single Bareos components and copy director with an already pre-installed database. You can also copy predefined configs if you wish Bareos v20 with an sqlite database, or mariadb/mysql for an older version of Bareos (I am happy not supported anymore because of lots of tuning to speed up). + #### 1. Install Bareos Director, Web UI, Storage, File daemon on the same host - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Install bareos-dir, web ui, -fd and -sd" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - role_action: install - bareos_components: dir_webui - init_bareos_database: "{{ (ansible_os_family == 'RedHat') }}" - postgresql_version: 14 +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Install bareos-dir, web ui, -fd and -sd" + ansible.builtin.include_role: + name: company.services.bareos + vars: + role_action: install + bareos_components: dir_webui + init_bareos_database: "{{ (ansible_os_family == 'RedHat') }}" + postgresql_version: 14 +``` #### 2. Make client user profile to access Bareos Web UI - - hosts: bareos_server_host - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Create Admin client user profile with webui-admin permissions to get full Web UI access" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - role_action: access - webui_username: Admin - webui_password: your_password_here - webui_profile: webui-admin - webui_tls_enable: false +```yaml +- hosts: bareos_server_host + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Create Admin client user profile with webui-admin permissions to get full Web UI access" + ansible.builtin.include_role: + name: company.services.bareos + vars: + role_action: access + webui_username: Admin + webui_password: your_password_here + webui_profile: webui-admin + webui_tls_enable: false +``` -You can set `webui-admin`, `operator`, `webui-limited` or `webui-readonly` access level (webui_profile) +You can set `webui-admin`, `operator`, `webui-limited` or `webui-readonly` access level (webui_profile) [your profile needs](https://docs.bareos.org/IntroductionAndTutorial/BareosWebui.html#access-control-configuration). For revoke access replace the next line: - role_action: access +```yaml + role_action: access +``` If you wish to prompt user and password during playbook execution: - vars_prompt: - - - name: "webui_username" - prompt: "Enter username" - default: "" - private: false - - name: "webui_password" - prompt: "Enter password" - default: "" - private: true - - tasks: - - - name: "Create Admin client user profile with webui-admin permissions to get full Web UI access" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - role_action: access - webui_profile: webui-admin - webui_tls_enable: false +```yaml + vars_prompt: + + - name: "webui_username" + prompt: "Enter username" + default: "" + private: false + - name: "webui_password" + prompt: "Enter password" + default: "" + private: true + + tasks: + + - name: "Create Admin client user profile with webui-admin permissions to get full Web UI access" + ansible.builtin.include_role: + name: company.services.bareos + vars: + role_action: access + webui_profile: webui-admin + webui_tls_enable: false +``` #### 3. Install Bareos file daemon and add to server To install a client, then add them to server, you can use separate groups for client(s) and server(s) in ansible inventory file, e.g.: - [clients] - 10.1.1.2 - 10.1.1.3 +```ini +[clients] +10.1.1.2 +10.1.1.3 - [server] - 10.1.1.1 +[server] +10.1.1.1 +``` and ansible playbook like: - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Install bareos file daemon(s) on host group clients" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - bareos_components: fd - role_action: install - when: inventory_hostname in groups["clients"] - - - name: "Add bareos file daemon(s) from host group clients to the first one of the host group servers" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - role_action: add_client - add_component_server: "{{ groups.servers[0] }}" - debug_mode: true - when: inventory_hostname in groups["clients"] +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Install bareos file daemon(s) on host group clients" + ansible.builtin.include_role: + name: company.services.bareos + vars: + bareos_components: fd + role_action: install + when: inventory_hostname in groups["clients"] + + - name: "Add bareos file daemon(s) from host group clients to the first one of the host group servers" + ansible.builtin.include_role: + name: company.services.bareos + vars: + role_action: add_client + add_component_server: "{{ groups.servers[0] }}" + debug_mode: true + when: inventory_hostname in groups["clients"] +``` #### 4. Install Bareos components with an additional list of packages - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Install bareos-dir, web ui, -fd and -sd" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - role_action: install - bareos_components: dir_webui - postgresql_version: 14 - init_bareos_database: "{{ (ansible_distribution == 'CentOS') }}" +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Install bareos-dir, web ui, -fd and -sd" + ansible.builtin.include_role: + name: company.services.bareos + vars: + role_action: install + bareos_components: dir_webui + postgresql_version: 14 + init_bareos_database: "{{ (ansible_distribution == 'CentOS') }}" +``` The example below shows how to install a client with only [**bareos-traymonitor**](https://docs.bareos.org/Configuration/Monitor.html) in the list of additional packages: - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Install bareos file daemon(s) and bareos-traymonitor" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - bareos_components: fd - role_action: install - install_additional_bareos_packages: - - bareos-traymonitor +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Install bareos file daemon(s) and bareos-traymonitor" + ansible.builtin.include_role: + name: company.services.bareos + vars: + bareos_components: fd + role_action: install + install_additional_bareos_packages: + - bareos-traymonitor +``` If the list (`install_additional_bareos_packages` variable) is empty Nothing will be installed additionally together with Bareos components. @@ -239,51 +257,57 @@ You can uninstall Bareos file daemon (fd), Bareos Storage Daemon (sd), Bareos di separately using `bareos_components` variable. The next example shows how to uninstall Bareos Storage Daemon from the host(s): - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Uninstall Bareos Storage Daemon" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - bareos_components: sd - role_action: uninstall +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Uninstall Bareos Storage Daemon" + ansible.builtin.include_role: + name: company.services.bareos + vars: + bareos_components: sd + role_action: uninstall +``` #### 6. Install Bareos with a pre-installed database and copy pre-defined configs The next example shows how to skip PostgreSQL installation and copy Bareos director configs from `files` folder of this role. Put your director configs to `files` folder of this role then run: - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Install bareos-dir, web ui, -fd and -sd; skip PostgreSQL install; copy configs to /etc/bareos-dir.d" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - bareos_components: dir_webui - use_postgresql: true - preinstalled_postgresql: true - bareos_configs_to_copy: - - source: etc/ - destination: /etc/bareos-dir.d - owner: bareos - group: bareos +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Install bareos-dir, web ui, -fd and -sd; skip PostgreSQL install; copy configs to /etc/bareos-dir.d" + ansible.builtin.include_role: + name: company.services.bareos + vars: + bareos_components: dir_webui + use_postgresql: true + preinstalled_postgresql: true + bareos_configs_to_copy: + - source: etc/ + destination: /etc/bareos-dir.d + owner: bareos + group: bareos +``` Nothing will be additionally copied if `bareos_configs_to_copy` list is empty. If you wish to use Bareos with an already preinstalled sqlite change set: - use_postgresql: false - preinstalled_postgresql: true +```yaml + use_postgresql: false + preinstalled_postgresql: true +``` #### 7. Copy Bareos configs without reinstalling @@ -291,72 +315,74 @@ You can upload configs to an already installed Bareos server without components component(s) should be restarted to apply configuration change in `bareos_components` variable. The example below shows how to apply bareos-dir, bareos-sd, bareos-fd and Bareos Web UI (by restart Apache web server): - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - - name: "Copy configs to /etc/bareos-dir.d without Bareos components reinstall" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.bareos - vars: - bareos_components: dir_webui - role_action: copy_configs - bareos_configs_to_copy: - - source: etc/ - destination: /etc/bareos-dir.d - owner: bareos - group: bareos +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + + - name: "Copy configs to /etc/bareos-dir.d without Bareos components reinstall" + ansible.builtin.include_role: + name: company.services.bareos + vars: + bareos_components: dir_webui + role_action: copy_configs + bareos_configs_to_copy: + - source: etc/ + destination: /etc/bareos-dir.d + owner: bareos + group: bareos +``` -Role Variables --------------- +## Role Variables -#### Main role variables: +#### Main role variables - **role_action** *[Default: install, possible values: install/uninstall/access/add_client/copy_configs]*: Role action -to be performed: install or uninstall Bareos components, create user profile to access Bareos Web UI *(access)*, add -already installed file daemon *(client)* on Bareos server *(add_client)*, copy Bareos config to already installed Bareos -component(s). + to be performed: install or uninstall Bareos components, create user profile to access Bareos Web UI *(access)*, add + already installed file daemon *(client)* on Bareos server *(add_client)*, copy Bareos config to already installed + Bareos component(s). - **bareos_components** *[Default: fd, possible values: fd, sd, dir, webui, dir_webui]*: Bareos components to install or -uninstall: Bareos file daemon or client *(fd)*, Bareos storage daemon *(sd)*, Bareos Director *(dir)*, Bareos director -and Web UI *(dir_webui)*. + uninstall: Bareos file daemon or client *(fd)*, Bareos storage daemon *(sd)*, Bareos Director *(dir)*, Bareos director + and Web UI *(dir_webui)*. - **clean_install** *[Default: true]*: Perform clean installation. All packages and configs will be purged before -install. -- **bareos_release** *[Default: 21]*: [Bareos release](https://download.bareos.org), e.g.: 'current', 'next' or -'experimental/'. Affects only for Debian and Redhat Linux distribution families. -- **bareos_url** *[Default: `current`]*: Bareos repository URL prefix to download from -(for example, if you with to use local or another repo). + install. +- **bareos_release** *[Default: 21]*: [Bareos release version](https://download.bareos.org/), e.g.: + 'current', 'next' or 'experimental/'. Affects only for Debian and Redhat Linux distribution families. +- **bareos_url** *[Default: https://download.bareos.org/]*: Bareos repository URL prefix to download from + (for example, if you with to use local or another repo). - **override_ansible_distribution_major_version** *[Default: None]*: Override ansible linux distribution major version. -Useful when specified Bareos version repo is not available for your Linux distribution version, but beware package -dependencies problems (example: Bareos v21 is not available for any RedHat v9, so try can set `8`). + Useful when specified Bareos version repo is not available for your Linux distribution version, but beware package + dependencies problems (example: Bareos v21 is not available for any RedHat v9, so try to set `8` here). - **debug_mode** *[Default: false]*: Verbose output. -#### Firewall related variables: +#### Firewall related variables - **firewall_control** *[Default: true]*: Add firewall rules for firewalld and ufw. -#### Bareos related variables: +#### Bareos related variables - **cleanup_storage_files** *[Default: true]*: Cleanup Bareos storage files on installation or uninstall. Please keep in -mind these files are useless without an indexes stored in the database. + mind these files are useless without an indexes stored in the database. - **install_additional_bareos_packages** *[Default: `[bareos-traymonitor]`]*: Additional Bareos packages to install: -`[]`or `[bareos-traymonitor, bareos-vmware-plugin]`, etc... + `[]`or `[bareos-traymonitor, bareos-vmware-plugin]`, etc... - **bareos_configs_to_copy**: [Default: `[{source: etc/, destination: /etc, owner: bareos, group: bareos}]`] List of -additional configs to copy on components install. Performs copying items from item.source to item.destination with -item.owner, item.group and item.mode, otherwise set this list to []. E. g: -```yaml -bareos_configs_to_copy: - - source: source/inside/files/folder_1 - destination: /destination/path/on/the/host_1 - owner: bareos - group: bareos - - source: source/inside/files/folder_2 - destination: /destination/path/on/the/host_2 - owner: bareos - group: bareos -``` + additional configs to copy on components install. Performs copying items from `item.source` to `item.destination` with + `item.owner`, `item.group` and `item.mode`, otherwise set this list to `[]`. E. g: + + ```yaml + bareos_configs_to_copy: + - source: source/inside/files/folder_1 + destination: /destination/path/on/the/host_1 + owner: bareos + group: bareos + - source: source/inside/files/folder_2 + destination: /destination/path/on/the/host_2 + owner: bareos + group: bareos + ``` For creating client user profile to access Bareos Web UI (role_action == *'access'*) you could use: @@ -382,7 +408,7 @@ To add file daemon on Bareos server, you could define the next variables: | add_component_server | 127.0.0.1 | Bareos server IP address, hostname or inventory item to delegate. | | add_component_force | false | Force try to add file daemon when already exists | -#### Database related parameters: +#### Database related parameters The most useful settings are stored in: @@ -396,24 +422,27 @@ version. Another variables: -- **postgresql_url** *[Default: `https://download.postgresql.org/pub/`]*: Download PostgreSQL repository URL prefix. -- **postgresql_debian_key_url** [Default: `https://www.postgresql.org/media/keys/ACCC4CF8.asc`]: PostgreSQL asc key URL +- **postgresql_url** *[Default: https://download.postgresql.org/pub/]*: Download PostgreSQL repository URL prefix. +- **postgresql_debian_key_url** [Default: https://www.postgresql.org/media/keys/ACCC4CF8.asc]: PostgreSQL asc key URL for Debian. - **postgresql_debian_keys_dir** *[Default: /etc/apt/keyrings]*: Debian apt keys destination path. - **postgresql_debian_key_destination** *[Default: `"{{ postgresql_debian_keys_dir }}/pgdg.asc"`]*: Debian apt keys full path. -- **postgresql_debian_apt_repo_url_prefix** *[Default: `http://apt.postgresql.org/pub/repos/apt/`]*: Debian PostgreSQL +- **postgresql_debian_apt_repo_url_prefix** *[Default: http://apt.postgresql.org/pub/repos/apt/]*: Debian PostgreSQL URL prefix for apt repo. - **postgresql_debian_repo** *[Default:* - ```yaml - deb [signed-by={{ postgresql_debian_key_destination }}] {{ postgresql_debian_apt_repo_url_prefix }} - {{ ansible_distribution_release }}-pgdg main - ``` + + ```jinja + deb [signed-by={{ postgresql_debian_key_destination }}] {{ postgresql_debian_apt_repo_url_prefix }} + {{ ansible_distribution_release }}-pgdg main + ``` + *]*: Debian PostgreSQL repo file content. + - **postgresql_become_user: postgres** *[Default: postgres]*: PostgreSQL become user to init Bareos database. - **init_bareos_database** *[Default: false]*: Call database and tables creation scripts. Required for old versions of Bareos or CentOS, because install scripts inside the packages are different. -License -------- -MIT-0 +## License + +BSD 3-Clause License diff --git a/roles/bareos/molecule/default/INSTALL.rst b/roles/bareos/molecule/default/INSTALL.rst index bfb6ed5..b187383 100644 --- a/roles/bareos/molecule/default/INSTALL.rst +++ b/roles/bareos/molecule/default/INSTALL.rst @@ -3,7 +3,7 @@ Requirements Ansible `molecule requirements`_ page available at: -.. _molecule requirements: ` +.. _molecule requirements: ` Please refer to the `Virtual environment`_ documentation for installation best practices. If not using a virtual environment, please consider passing the diff --git a/roles/lxcfs/.ansible-lint b/roles/lxcfs/.ansible-lint index 343465f..82299e6 100644 --- a/roles/lxcfs/.ansible-lint +++ b/roles/lxcfs/.ansible-lint @@ -1,21 +1,12 @@ --- -### ansible linter config -### -### more details: -### - https://ansible-lint.readthedocs.io/en/latest/configuring/#configuration-file -### Please keep in mind how to skip rule inside a playbook/role: -### - https://ansible-lint.readthedocs.io/en/latest/rules/#false-positives-skipping-rules +# ansible-lint config +# see: https://ansible.readthedocs.io/projects/lint/usage/#specifying-rules-at-runtime +# https://ansible.readthedocs.io/projects/lint/usage/#muting-warnings-to-avoid-false-positives -exclude_paths: - - .idea/ - - .git/ - - .scripts/ - - .gilab-ci.yml - - .gitignore - - .gitmodules quiet: true verbosity: 1 +# exclude_paths: # skip_list: # enable_list: # warn_list: \ No newline at end of file diff --git a/roles/lxcfs/.flake8 b/roles/lxcfs/.flake8 deleted file mode 100644 index 151ddda..0000000 --- a/roles/lxcfs/.flake8 +++ /dev/null @@ -1,7 +0,0 @@ -[flake8] -ignore = E126,E131,E501,E303,E302,W391,W503,W292 -exclude = - .git, - __pycache__, - .venv - .tests_tmpl \ No newline at end of file diff --git a/roles/lxcfs/.yamllint b/roles/lxcfs/.yamllint index 0108629..d48acff 100644 --- a/roles/lxcfs/.yamllint +++ b/roles/lxcfs/.yamllint @@ -6,7 +6,10 @@ ignore: | rules: braces: + min-spaces-inside: 0 max-spaces-inside: 1 + min-spaces-inside-empty: 0 + max-spaces-inside-empty: 0 level: error brackets: max-spaces-inside: 1 @@ -19,7 +22,7 @@ rules: level: error comments: disable comments-indentation: disable - document-start: disable + document-start: enable empty-lines: max: 2 level: error @@ -36,4 +39,4 @@ rules: trailing-spaces: enable truthy: allowed-values: ['true', 'false'] - check-keys: true + check-keys: true \ No newline at end of file diff --git a/roles/lxcfs/README.md b/roles/lxcfs/README.md index 38f8995..5bd0e37 100644 --- a/roles/lxcfs/README.md +++ b/roles/lxcfs/README.md @@ -1,51 +1,55 @@ -lxcfs -===== +# lxcfs + Installs and configures [lxc](https://linuxcontainers.org/lxc/introduction/) or [lxcfs](https://linuxcontainers.org/lxcfs/introduction/) on linux system. -Requirements ------------- -- Any Debian or Ubuntu (tested on LTS version, but perhaps work on any version), any RedHat and Alpine Linux +## Requirements + +- Any Debian or Ubuntu (tested on LTS version, but perhaps work on any version), any RedHat and Alpine Linux distributive. - jmespath installed: `python3 -m pip install jmespath`. -Role Variables --------------- +## Role Variables + - `role_action` - role action to perform, e.g: `install` or `uninstall`. - `clean_install` - perform clean installation of lxc/lxcfs. - `lxc_version` - version of lxc/lxcfs, e.g: `3.0` or `2.0`. Affects only on RedHat repository URL. Please note: there -is no lxcfs for 2.0, only lxc. + is no lxcfs for 2.0, only lxc. - `lxc_technology` - container technology to install: `lxc` or `lxcfs`. - `lxc_gpg_keyserver` - add LXC GPG keyserver (`DOWNLOAD_KEYSERVER`) to environment variables, e.g: -`keyserver.ubuntu.com`. + `keyserver.ubuntu.com`. - `check_host_is_lxc_ready` - check host is lxc-ready (run `lxc-checkconfig` command when *true*). Version of lxc may -differ from distribution to distribution where lxc-checkconfig script could be + differ from distribution to distribution where lxc-checkconfig script could be [a bit outdated](https://github.com/lxc/lxc/issues/4070#issuecomment-1374883653). -- `append_lxc_config` - append config lines to default lxc config. Paste something for default container settings, e.g: -``` -append_lxc_config: | - lxc.net.0.type = veth - lxc.net.0.link = lxcbr0 - lxc.net.0.name = eth0 - lxc.net.0.flags = up - lxc.net.0.hwaddr = 00:16:3e:xx:xx:xx - lxc.net.0.veth.pair = pariname-lxc - lxc.net.0.ipv4.address = 10.0.0.200/24 - lxc.net.0.ipv4.gateway = 10.0.0.254 - lxc.start.auto = 1 - lxc.start.delay = 8 -``` -for LXC3.0 or: -``` - lxc.network.type = veth - lxc.network.link = lxcbr0 - lxc.network.flags = up - lxc.start.auto = 1 - lxc.start.delay = 8 -``` -for LXC2.0. So `append_lxc_config` lines will append to all new created containers configs. - -## lxc-net settings +- `append_lxc_config` - append config lines to default lxc config. Paste something for default container settings, e.g.: + + ```yaml + append_lxc_config: | + lxc.net.0.type = veth + lxc.net.0.link = lxcbr0 + lxc.net.0.name = eth0 + lxc.net.0.flags = up + lxc.net.0.hwaddr = 00:16:3e:xx:xx:xx + lxc.net.0.veth.pair = pariname-lxc + lxc.net.0.ipv4.address = 10.10.12.200/24 + lxc.net.0.ipv4.gateway = 10.10.12.254 + lxc.start.auto = 1 + lxc.start.delay = 8 + ``` + + for LXC3.0 or: + + ```yaml + lxc.network.type = veth + lxc.network.link = lxcbr0 + lxc.network.flags = up + lxc.start.auto = 1 + lxc.start.delay = 8 + ``` + + for LXC2.0. So `append_lxc_config` lines will append to all new created containers configs. + +### lxc-net settings - `use_lxc_default_net` - use default lxc bridge-nat network (`lxc-net` daemon) bind to `lxc_default_net_bridge` interface. Disable (set `false`) if you want to connect with host bridge, pass-through, etc. @@ -56,29 +60,33 @@ interface. Disable (set `false`) if you want to connect with host bridge, pass-t - `lxc_default_net_dhcp_range` - DHCP range for bridge-nat network, e.g.: `"10.0.3.2,10.0.3.254"`. - `lxc_default_net_dhcp_max` - max number of DHCP leases in `lxc_default_net_dhcp_range`, e.g.: `"253"`. -Example Playbook ----------------- +## Example Playbook Simple lxc role usage with defaults is: - - hosts: all - become: true - become_method: sudo - gather_facts: true - - tasks: - - name: Include lxc(fs) role - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.lxcfs - vars: - lxc_technology: lxc +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true + + tasks: + - name: Include lxc(fs) role + ansible.builtin.include_role: + name: common.linux.lxcfs + vars: + lxc_technology: lxc +``` You can also switch to lxcfs with: - lxc_technology: lxcfs +```yaml + lxc_technology: lxcfs +``` More complex lxcfs usage with disabled default lxc-net for br0 usage with some static addresses should look like: +```yaml - hosts: all become: true become_method: sudo @@ -90,7 +98,7 @@ More complex lxcfs usage with disabled default lxc-net for br0 usage with some s - name: Include lxc(fs) role ansible.builtin.include_role: - name: alexanderbazhenoff.linux.lxcfs + name: common.linux.lxcfs vars: lxc_technology: lxcfs use_lxc_default_net: false @@ -102,11 +110,12 @@ More complex lxcfs usage with disabled default lxc-net for br0 usage with some s lxc.net.0.veth.pair = someprefix-lxc lxc.net.0.name = eth0 lxc.net.0.link = br0 - lxc.net.0.ipv4.address = 10.0.0.200/24 - lxc.net.0.ipv4.gateway = 10.0.0.254 + lxc.net.0.ipv4.address = 10.10.12.200/24 + lxc.net.0.ipv4.gateway = 10.10.12.254 lxc.start.auto = 1 lxc.start.delay = 8 +``` + +## License -License -------- -MIT-0 +BSD 3-Clause License diff --git a/roles/postgresql/.ansible-lint b/roles/postgresql/.ansible-lint index 9d5968a..e1f738c 100644 --- a/roles/postgresql/.ansible-lint +++ b/roles/postgresql/.ansible-lint @@ -1,17 +1,12 @@ --- -### ansible linter config -### -### more details: -### - https://ansible-lint.readthedocs.io/en/latest/configuring/#configuration-file -### Please keep in mind how to skip rule inside a playbook/role: -### - https://ansible-lint.readthedocs.io/en/latest/rules/#false-positives-skipping-rules +# ansible-lint config +# see: https://ansible.readthedocs.io/projects/lint/usage/#specifying-rules-at-runtime +# https://ansible.readthedocs.io/projects/lint/usage/#muting-warnings-to-avoid-false-positives -exclude_paths: - - .gitignore - - .gitmodules quiet: true verbosity: 1 +# exclude_paths: # skip_list: # enable_list: # warn_list: diff --git a/roles/postgresql/.yamllint b/roles/postgresql/.yamllint index b45b2f6..d48acff 100644 --- a/roles/postgresql/.yamllint +++ b/roles/postgresql/.yamllint @@ -1,5 +1,4 @@ --- - # Based on ansible-lint config extends: default ignore: | @@ -7,7 +6,10 @@ ignore: | rules: braces: + min-spaces-inside: 0 max-spaces-inside: 1 + min-spaces-inside-empty: 0 + max-spaces-inside-empty: 0 level: error brackets: max-spaces-inside: 1 @@ -20,7 +22,7 @@ rules: level: error comments: disable comments-indentation: disable - document-start: disable + document-start: enable empty-lines: max: 2 level: error @@ -37,4 +39,4 @@ rules: trailing-spaces: enable truthy: allowed-values: ['true', 'false'] - check-keys: true + check-keys: true \ No newline at end of file diff --git a/roles/postgresql/README.md b/roles/postgresql/README.md index c7fa22d..c43006f 100644 --- a/roles/postgresql/README.md +++ b/roles/postgresql/README.md @@ -1,52 +1,49 @@ -postgresql -========== +# postgresql Installs and manages PostgreSQL database instance. -Specification -------------- +## Specification -### 1. Install, uninstall and configuring. +### 1. Install, uninstall and configuring This role provides the following install, uninstall and/or configuring operations: - Install or uninstall a specified version of PostgreSQL database server (or database instance). When specified -PostgreSQL version repository is not available for your Linux distribution, this will install a default (or recommended) -version for your Linux distribution (see [example playbooks](#1-install-or-uninstall-postgresql-server-instance) for -details). + PostgreSQL version repository is not available for your Linux distribution, this will install a default (or + recommended) version for your Linux distribution (see + [example playbooks](#1-install-or-uninstall-postgresql-server-instance) for details). - Install or uninstall [pgadmin4](https://www.pgadmin.org/) alongside or single from database instance: pgadmin4 web -version with Apache, pgadmin desktop version or both (see [example playbook tasks](#2-install-or-uninstall-pgadmin4) for -details). + version with Apache, pgadmin desktop version or both (see [example playbook tasks](#2-install-or-uninstall-pgadmin4) + for details). - Applies firewall rules (ufw and firewalld) for database instance and/or pgadmin4 web version installation. Removes -firewall rules during uninstalling. -- Configure `pg_hba.conf` on already installed database instance (see [example playbook tasks](#3-configure-pg_hbaconf)). + firewall rules during uninstalling. +- Configure `pg_hba.conf` on already installed database instance (see + [example playbook tasks](#3-configure-pg_hbaconf)). - Configure `postgresql.conf` on already installed database instance -([example playbook tasks](#4-configure-postgresqlconf)). + ([example playbook tasks](#4-configure-postgresqlconf)). Limitations: - Alpine Linux is not supported for pgadmin4 installation. - Configuring iptables for Debian systems is not supported. -### 2. Management. +### 2. Management - Create, alter, or remove a user (role) from a PostgreSQL server instance (see [example playbook tasks](#5-user-role-management) for details). - Create, drop, dump, rename or restore PostgreSQL databases (see [example playbook tasks](#6-database-management) for -details). + details). - Add or remove PostgreSQL schemas ([example playbook tasks](#7-schemas-management)). - Grant or revoke privileges on PostgreSQL database objects ([example playbook tasks](#8-privileges-management)). - Add or remove replication slots from a PostgreSQL database ([example playbook tasks](#9-slots-management)). -Requirements ------------- +## Requirements - Any LTS version of Ubuntu. Any version of Debian, RHEL, Centos, Fedora, Oracle Linux and Alpine Linux. - Before you run this role on Alpine Linux set your `/etc/apk/repositories` manually (read -[documentation](https://wiki.alpinelinux.org/wiki/Repositories)). + [documentation](https://wiki.alpinelinux.org/wiki/Repositories)). -Dependencies ------------- +## Dependencies - [community.general](https://docs.ansible.com/ansible/latest/collections/community/general/index.html) ansible collection to install/uninstall PostgreSQL packages on Alpine Linux. @@ -54,91 +51,102 @@ Dependencies collection to control database instance using this role. - This role using 'sudo' become method, so Debian distribution should have them already pre-installed. -Example Playbooks ------------------ +## Example Playbooks -#### 1. Install or uninstall PostgreSQL server instance +### 1. Install or uninstall PostgreSQL server instance The shortest example playbook of database instance installation should look like: - - hosts: all - become: true - become_method: sudo - gather_facts: true +```yaml +- hosts: all + become: true + become_method: sudo + gather_facts: true - tasks: + tasks: - - name: "Install PostgreSQL v15 instance(es)" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql + - name: "Install PostgreSQL v15 instance(es)" + ansible.builtin.include_role: + name: common.linux.postgresql +``` -while uninstall of the same version playbook tasks should look like: +while uninstall of the same version, playbook tasks should look like: - - name: "Uninstall PostgreSQL v15 instance(es) without database directory clean-up" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: uninstall +```yaml + - name: "Uninstall PostgreSQL v15 instance(es) without database directory clean-up" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: uninstall +``` Role checks that specified version of PostgreSQL server is available for your Linux distribution: if this version is not available, this will install a default version from your distribution repositories or from dnf modules. If you wish to install PostgreSQL of a default version for your linux destribution set `postgresql_recommended_version: true`: - - name: "Install PostgreSQL of default version for your linux destribution" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - postgresql_recommended_version: true +```yaml + - name: "Install PostgreSQL of default version for your linux destribution" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + postgresql_recommended_version: true +``` More complex examples may include different customisations: - - name: "Install PostgreSQL v16 with postgresql.conf change and some packages alongside with pgadmin4 web" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - postgresql_version: 16 - install_pgadmin: true - pgadmin_email: john.doe@company.com - pgadmin_password: some_password_here - postgresql_additional_packages: - - "postgresql{% if ansible_os_family == 'Debian' %}-client-{{ postgresql_version }}{% else -%} - {{ postgresql_version }}-contrib{% endif %}" - postgresql_conf: - port: 5432 - max_connections: 1000 - superuser_reserved_connections: 10 - listen_addresses: "'*'" - lc_messages: "'en_US.UTF-8'" - -#### 2. Install or uninstall pgadmin4 +```yaml + - name: "Install PostgreSQL v16 with postgresql.conf change and some packages alongside with pgadmin4 web" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + postgresql_version: 16 + install_pgadmin: true + pgadmin_email: john.doe@company.com + pgadmin_password: some_password_here + postgresql_additional_packages: + - "postgresql{% if ansible_os_family == 'Debian' %}-client-{{ postgresql_version }}{% else -%} + {{ postgresql_version }}-contrib{% endif %}" + postgresql_conf: + port: 5432 + max_connections: 1000 + superuser_reserved_connections: 10 + listen_addresses: "'*'" + lc_messages: "'en_US.UTF-8'" +``` + +### 2. Install or uninstall pgadmin4 You can also install pgadmin4 web version without database server instance: - - name: "Install pgadmin4 web version" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: install - role_subject: pgadmin - pgadmin_email: john.doe@company.com - pgadmin_password: some_password_here +```yaml + - name: "Install pgadmin4 web version" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: install + role_subject: pgadmin + pgadmin_email: john.doe@company.com + pgadmin_password: some_password_here +``` Credentials required for pgadmin web login. Install pgadmin4 desktop version: - - name: "Install pgadmin4 desktop version" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: install - role_subject: pgadmin - pgadmin_installation_type: desktop - pgadmin_email: john.doe@company.com - pgadmin_password: some_password_here +```yaml + - name: "Install pgadmin4 desktop version" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: install + role_subject: pgadmin + pgadmin_installation_type: desktop + pgadmin_email: john.doe@company.com + pgadmin_password: some_password_here +``` -To install pgadmin4 desktop locally run playbook from [examples folder](examples) with specified credentials variables, -e.g: +To install pgadmin4 desktop locally, run playbook from [examples folder](examples) with specified credentials variables, +e.g.: ```bash cd @@ -146,70 +154,78 @@ ansible-playbook -c local -i localhost, examples/install_pgadmin4_desktop.yml -- "ansible_python_interpreter=/usr/bin/python3 become_password=" ``` -#### 3. Configure pg_hba.conf +### 3. Configure pg_hba.conf You can perform regex search and add line(s) to pg_hba.conf running the next playbook tasks, e.g: - - name: "Perform regex search and add line(s) to pg_hba.conf" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: configure - role_subject: hba_conf - pg_conf_content_mode: regex - hba_conf_content: | - local all postgres trust +```yaml + - name: "Perform regex search and add line(s) to pg_hba.conf" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: configure + role_subject: hba_conf + pg_conf_content_mode: regex + hba_conf_content: | + local all postgres trust +``` Replace mode will write the whole content of `hba_conf_content` variable to pg_hba.conf file: - - name: "Configure the whole pg_hba.conf" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: configure - role_subject: hba_conf - pg_conf_content_mode: replace - hba_conf_content: | - local all postgres trust - local all all trust - host all all 127.0.0.1/32 trust - host all all 0.0.0.0/24 md5 - host all all ::1/128 trust - host all all 0.0.0.0/0 md5 - local replication all peer - host replication all 127.0.0.1/32 trust - host replication all ::1/128 trust - host replication all 0.0.0.0/24 scram-sha-256 - host replication all 0.0.0.0/0 scram-sha-256 +```yaml + - name: "Configure the whole pg_hba.conf" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: configure + role_subject: hba_conf + pg_conf_content_mode: replace + hba_conf_content: | + local all postgres trust + local all all trust + host all all 127.0.0.1/32 trust + host all all 0.0.0.0/24 md5 + host all all ::1/128 trust + host all all 0.0.0.0/0 md5 + local replication all peer + host replication all 127.0.0.1/32 trust + host replication all ::1/128 trust + host replication all 0.0.0.0/24 scram-sha-256 + host replication all 0.0.0.0/0 scram-sha-256 +``` Or you can use templating from a specified location: - - name: "Templating pg_hba.conf from /path/to/your/hba_conf/template/file" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: configure - role_subject: hba_conf - pg_conf_content_mode: /path/to/your/hba_conf/template/file +```yaml + - name: "Templating pg_hba.conf from /path/to/your/hba_conf/template/file" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: configure + role_subject: hba_conf + pg_conf_content_mode: /path/to/your/hba_conf/template/file +``` Using this role all `pg_hba.conf` change actions ends up with postgresql daemon restart. Please note all settings above are not the only recommendations, check the [official documentation](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html). -#### 4. Configure postgresql.conf +### 4. Configure postgresql.conf - - name: "Change postgresql.conf parameters" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: configure - role_subject: postgresql_conf - postgresql_conf: - max_connections: 1000 - log_connections: 'yes' - listen_addresses: "'*'" - lc_messages: "'en_US.UTF-8'" +```yaml + - name: "Change postgresql.conf parameters" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: configure + role_subject: postgresql_conf + postgresql_conf: + max_connections: 1000 + log_connections: 'yes' + listen_addresses: "'*'" + lc_messages: "'en_US.UTF-8'" +``` will set the next parameters to postgresql.conf file: @@ -221,675 +237,689 @@ lc_messages = 'en_US.UTF-8' ``` All parameters will be written after the comments containing defaults. You can also split parameters and pass them into -playbook tasks how many times as you wish. If you set another value on existing parameter this will overwrite with the +playbook tasks how many times as you wish. If you set another value on existing parameter, this will overwrite with the last one. Using this role all `postgresql.conf` change actions ends up with postgresql daemon restart. -#### 5. User (role) management - - - name: "Create django user (role) on PostgreSQL server instance" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: users - postgresql_users: - - name: django - password: ceec4eif7ya - - - name: "Add a comment on django user" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: users - postgresql_users: - - name: django - comment: This is a test user - - - name: "Create rails user, set MD5-hashed password, grant privs" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: users - postgresql_users: - - name: rails - password: md59543f1d82624df2b31672ec0f7050460 - role_attr_flags: CREATEDB,NOSUPERUSER - - - name: "Connect to acme database and remove test user" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: drop - role_subject: users - postgresql_users: - - name: test - database: acme - fail_on_user: false - - - name: "Connect to test database and remove an existing user's password" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: drop - role_subject: users - postgresql_users: - - name: test - database: test - password: "" - -#### 6. Database management - - - name: "Create a new database with name 'acme'" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: databases - postgresql_databases: - - name: acme - - # Note: If a template different from "template0" is specified, - # encoding and locale settings must match those of the template. - - name: "Create a new database with name 'acme' with specific encoding, locale and owner" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: databases - postgresql_databases: - - name: acme - owner: user - encoding: UTF-8 - lc_collate: de_DE.UTF-8 - lc_ctype: de_DE.UTF-8 - template: template0 - - # Note: Default limit for the number of concurrent connections to - # a specific database is "-1", which means "unlimited" - - name: "Create a new databases with name 'acme' and 'django' which has a limit of 100 concurrent connections" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: databases - postgresql_databases: - - name: acme - conn_limit: "100" - - name: django - conn_limit: "100" - - - name: "Dump an existing databases to a file" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: dump - role_subject: databases - postgresql_databases: - - name: acme - target: /tmp/acme.sql - - name: django - target: /tmp/django.sql - - - name: "Dump an existing database to a file excluding the test table" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: dump - role_subject: databases - postgresql_databases: - - name: acme - target: /tmp/acme.sql - dump_extra_args: --exclude-table=test - - - name: "Dump an existing database to a file (with compression)" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: dump - role_subject: databases - postgresql_databases: - - name: acme - target: /tmp/acme.sql.gz - - - name: "Dump a single schema for an existing database" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: dump - role_subject: databases - postgresql_databases: - - name: acme - target: /tmp/acme.sql - target_opts: "-n public" - - - name: "Dump only table1 and table2 from the acme database" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: dump - role_subject: databases - postgresql_databases: - - name: acme - target: /tmp/table1_table2.sql - target_opts: "-t table1 -t table2" - - - name: "Dump an existing database using the directory format" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: dump - role_subject: databases - postgresql_databases: - - name: acme - target: /tmp/acme.dir - - # Note: In the example below, if database foo exists and has another tablespace - # the tablespace will be changed to foo. Access to the database will be locked - # until the copying of database files is finished. - - name: "Create a new database called foo in tablespace bar" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: databases - postgresql_databases: - - name: foo - tablespace: bar - - # Rename the database foo to bar. - # If the database foo exists, it will be renamed to bar. - # If the database foo does not exist and the bar database exists, - # the module will report that nothing has changed. - # If both the databases exist, an error will be raised. - - name: "Rename the database foo to bar" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: rename - role_subject: databases - postgresql_databases: - - name: foo - target: bar - -#### 7. Schemas management - - - name: "Create a new schema with name acme in test database" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: schemas - postgresql_schemas: - - database: test - name: acme - - - name: "Create a new schema acme with a user bob who will own it" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: schemas - postgresql_schemas: - - name: acme - owner: bob - - - name: "Drop schema 'acme' with cascade" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: drop - role_subject: schemas - postgresql_schemas: - - name: acme - cascade_drop: true - -#### 8. Privileges management - - # On database "library": - # GRANT SELECT, INSERT, UPDATE ON TABLE public.books, public.authors - # TO librarian, reader WITH GRANT OPTION - - name: "Grant privs to librarian and reader on database library" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - privs: SELECT,INSERT,UPDATE - type: table - objs: books,authors - schema: public - roles: librarian,reader - grant_option: true - - - name: "Same as above leveraging default values" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - privs: SELECT,INSERT,UPDATE - objs: books,authors - roles: librarian,reader - grant_option: true - - # REVOKE GRANT OPTION FOR INSERT ON TABLE books FROM reader - # Note that role "reader" will be *granted* INSERT privilege itself if this - # isn't already the case (since state: present). - - name: "Revoke privs from reader" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - priv: INSERT - obj: books - role: reader - grant_option: false - - # "public" is the default schema. This also works for PostgreSQL 8.x. - - name: "REVOKE INSERT, UPDATE ON ALL TABLES IN SCHEMA public FROM reader" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: revoke - role_subject: privileges - postgresql_privileges: - - database: library - privs: INSERT,UPDATE - objs: ALL_IN_SCHEMA - role: reader - - - name: "GRANT ALL PRIVILEGES ON SCHEMA public, math TO librarian" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - privs: ALL - type: schema - objs: public,math - role: librarian - - # Note the separation of arguments with colons. - - name: "GRANT ALL PRIVILEGES ON FUNCTION math.add(int, int) TO librarian, reader" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - privs: ALL - type: function - obj: add(int:int) - schema: math - roles: librarian,reader - - # Note that group role memberships apply cluster-wide and therefore are not - # restricted to database "library" here. - - name: "GRANT librarian, reader TO alice, bob WITH ADMIN OPTION" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - type: group - objs: librarian,reader - roles: alice,bob - admin_option: true - - # Note that here "db: postgres" specifies the database to connect to, not the - # database to grant privileges on (which is specified via the "objs" param) - - name: "GRANT ALL PRIVILEGES ON DATABASE library TO librarian" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: postgres - privs: ALL - type: database - obj: library - role: librarian - - # If objs is omitted for type "database", it defaults to the database - # to which the connection is established - - name: "GRANT ALL PRIVILEGES ON DATABASE library TO librarian" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - privs: ALL - type: database - role: librarian - - # Objs must be set, ALL_DEFAULT to TABLES/SEQUENCES/TYPES/FUNCTIONS - # ALL_DEFAULT works only with privs=ALL - # For specific - - name: "ALTER DEFAULT PRIVILEGES ON DATABASE library TO librarian" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - objs: ALL_DEFAULT - privs: ALL - type: default_privs - role: librarian - grant_option: true - - # Objs must be set, ALL_DEFAULT to TABLES/SEQUENCES/TYPES/FUNCTIONS - # ALL_DEFAULT works only with privs=ALL - # For specific - - name: "ALTER DEFAULT PRIVILEGES ON DATABASE library TO reader, step 1" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - objs: TABLES,SEQUENCES - privs: SELECT - type: default_privs - role: reader - - - name: "ALTER DEFAULT PRIVILEGES ON DATABASE library TO reader, step 2" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - objs: TYPES - privs: USAGE - type: default_privs - role: reader - - - name: "GRANT ALL PRIVILEGES ON FOREIGN DATA WRAPPER fdw TO reader" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: test - objs: fdw - privs: ALL - type: foreign_data_wrapper - role: reader - - # Available since community.postgresql 0.2.0 - - name: "GRANT ALL PRIVILEGES ON TYPE customtype TO reader" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: test - objs: customtype - privs: ALL - type: type - role: reader - - - name: "GRANT ALL PRIVILEGES ON FOREIGN SERVER fdw_server TO reader" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: test - objs: fdw_server - privs: ALL - type: foreign_server - role: reader - - # Grant 'execute' permissions on all functions in schema 'common' to role 'caller' - - name: "GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA common TO caller" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - type: function - privs: EXECUTE - roles: caller - objs: ALL_IN_SCHEMA - schema: common - - # Available since collection version 1.3.0 - # Grant 'execute' permissions on all procedures in schema 'common' to role 'caller' - # Needs PostreSQL 11 or higher and community.postgresql 1.3.0 or higher - - name: "GRANT EXECUTE ON ALL PROCEDURES IN SCHEMA common TO caller" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - type: prucedure - privs: EXECUTE - roles: caller - objs: ALL_IN_SCHEMA - schema: common - - # ALTER DEFAULT PRIVILEGES FOR ROLE librarian IN SCHEMA library GRANT SELECT ON TABLES TO reader - # GRANT SELECT privileges for new TABLES objects created by librarian as - # default to the role reader. - # For specific - - name: "ALTER privs" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: library - schema: library - objs: TABLES - privs: SELECT - type: default_privs - role: reader - target_roles: librarian - - # ALTER DEFAULT PRIVILEGES FOR ROLE librarian IN SCHEMA library REVOKE SELECT ON TABLES FROM reader - # REVOKE SELECT privileges for new TABLES objects created by librarian as - # default from the role reader. - # For specific - - name: "ALTER privs" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: revoke - role_subject: privileges - postgresql_privileges: - - database: library - schema: library - objs: TABLES - privs: SELECT - type: default_privs - role: reader - target_roles: librarian - - # Available since community.postgresql 0.2.0 - - name: "Grant type privileges for pg_catalog.numeric type to alice" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - type: type - roles: alice - privs: ALL - objs: numeric - schema: pg_catalog - database: acme - - - name: "Alter default privileges grant usage on schemas to datascience" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: grant - role_subject: privileges - postgresql_privileges: - - database: test - type: default_privs - privs: usage - objs: schemas - role: datascience - -#### 9. Slots management - - - name: "Create physical_one physical slot if doesn't exist" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: slots - postgresql_slots: - - name: physical_one - database: ansible - become_user: postgres - - - name: "Remove physical_one slot if exists" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: drop - role_subject: slots - postgresql_slots: - - name: physical_one - database: ansible - become_user: postgres - - - name: "Create logical_one logical slot to the database acme if doesn't exist" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: create - role_subject: slots - postgresql_slots: - - name: logical_slot_one - slot_type: logical - output_plugin: custom_decoder_one - database: "acme" - - - name: "Remove logical_one slot if exists from the cluster running on another host and non-standard port" - ansible.builtin.include_role: - name: alexanderbazhenoff.linux.postgresql - vars: - role_action: drop - role_subject: slots - postgresql_slots: - - name: logical_one - login_host: mydatabase.example.org - port: 5433 - login_user: ourSuperuser - login_password: thePassword - -Role Variables --------------- - -### Role parameters: - -| Variable | Default | Comment | -|--------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------| -| role_action | install | Role action: uninstall, install, configure, create, grant, drop, revoke, dump, rename, restore | -| role_subject | server | Role subject to perform with: server, pgadmin, hba_conf, postgresql_conf, users, databases, privileges, schemas, slots | -| clean_install | true | Perform clean install | -| postgresql_version | 15 | Version of pgsql repository | -| cleanup_data_directory | true | Clean-up PostgreSQL data directory | -| postgresql_recommended_version | false | Install recommended version for current Linux distribution (1) | -| postgresql_additional_packages | [] | List of additional PostgreSQL related packages to install (2) | -| install_psycopg2 | true | Install [psycopg2](https://pypi.org/project/psycopg2/) | -| install_pgadmin | false | Install [pgadmin4](https://www.pgadmin.org/) for web mode alongside with postgresql server | -| pgadmin_installation_type | web | pgadmin installation type: web or desktop. Leave them empty to install both web and desktop. | -| firewall_control | true | Add or remove firewalld and/or ufw rules on install or uninstall. Will be skipped when firewall disabled. | - -* (1) Recommended version install based on distribution repository or -[dnf modules](https://docs.fedoraproject.org/en-US/modularity/using-modules/). Useful when the current version of -PostgreSQL server instance is not available for your Linux distribution (e.g. check -[RedHat repository](https://www.postgresql.org/download/linux/redhat/)). - -* (2) List of additional PostgreSQL related packages, e.g: 'postgresql-contrib' or 'postgresql14-contrib' for -`postgresql_recommended_version: true` (explore what packages available -[here](https://www.postgresql.org/download/linux/)). There is no automated version handling in this list, include -versions to package names. - -### PostgreSQL server (or database instance) parameters: - -* **postgresql_default_timezone**. PostgreSQL timezone. Required for PostgreSQL v14+, especially for init server -instance data directory on Alpine Linux. You can change it later, e.g: `SET TIME ZONE 'America/Montreal';` and/or add: -`timezone: 'America/Montreal'` to `postgresql_conf` dict variable (See also a -[list of timezone names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). Defaults: 'Europe/Moscow' - -* **postgresql_conf** (dict). Parameters from postgresql.conf with the same name here (see -[documentation](https://www.postgresql.org/docs/current/config-setting.html)). Double quotes to keep single -`'quotes of value'`. Defaults: +### 5. User (role) management + ```yaml - port: 5432 - max_connections: 100 - superuser_reserved_connections: 3 - listen_addresses: "'*'" + - name: "Create django user (role) on PostgreSQL server instance" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: users + postgresql_users: + - name: django + password: ceec4eif7ya + + - name: "Add a comment on django user" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: users + postgresql_users: + - name: django + comment: This is a test user + + - name: "Create rails user, set MD5-hashed password, grant privs" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: users + postgresql_users: + - name: rails + password: md59543f1d82624df2b31672ec0f7050460 + role_attr_flags: CREATEDB,NOSUPERUSER + + - name: "Connect to acme database and remove test user" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: drop + role_subject: users + postgresql_users: + - name: test + database: acme + fail_on_user: false + + - name: "Connect to test database and remove an existing user's password" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: drop + role_subject: users + postgresql_users: + - name: test + database: test + password: "" ``` -* **pg_conf_content_mode** (string). `pg_hba.conf` write content mode to perform configure hba_conf (see -[documentation](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)): `regex` (ensure line(s) presents) or -`block` (replace original file with), otherwise set template filename here (from /templates sub-folder) or full path to -replace with (e.g. `pg_hba.conf.j2`). Defaults: `pg_hba.conf.j2` -* **hba_conf_content** (string). pg_hba.conf block or lines for regex mode. Defaults: `''` +### 6. Database management + +```yaml + - name: "Create a new database with name 'acme'" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: databases + postgresql_databases: + - name: acme + + # Note: If a template different from "template0" is specified, + # encoding and locale settings must match those of the template. + - name: "Create a new database with name 'acme' with specific encoding, locale and owner" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: databases + postgresql_databases: + - name: acme + owner: user + encoding: UTF-8 + lc_collate: de_DE.UTF-8 + lc_ctype: de_DE.UTF-8 + template: template0 + + # Note: Default limit for the number of concurrent connections to + # a specific database is "-1", which means "unlimited" + - name: "Create a new databases with name 'acme' and 'django' which has a limit of 100 concurrent connections" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: databases + postgresql_databases: + - name: acme + conn_limit: "100" + - name: django + conn_limit: "100" + + - name: "Dump an existing databases to a file" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: dump + role_subject: databases + postgresql_databases: + - name: acme + target: /tmp/acme.sql + - name: django + target: /tmp/django.sql + + - name: "Dump an existing database to a file excluding the test table" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: dump + role_subject: databases + postgresql_databases: + - name: acme + target: /tmp/acme.sql + dump_extra_args: --exclude-table=test + + - name: "Dump an existing database to a file (with compression)" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: dump + role_subject: databases + postgresql_databases: + - name: acme + target: /tmp/acme.sql.gz + + - name: "Dump a single schema for an existing database" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: dump + role_subject: databases + postgresql_databases: + - name: acme + target: /tmp/acme.sql + target_opts: "-n public" + + - name: "Dump only table1 and table2 from the acme database" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: dump + role_subject: databases + postgresql_databases: + - name: acme + target: /tmp/table1_table2.sql + target_opts: "-t table1 -t table2" + + - name: "Dump an existing database using the directory format" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: dump + role_subject: databases + postgresql_databases: + - name: acme + target: /tmp/acme.dir + + # Note: In the example below, if database foo exists and has another tablespace + # the tablespace will be changed to foo. Access to the database will be locked + # until the copying of database files is finished. + - name: "Create a new database called foo in tablespace bar" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: databases + postgresql_databases: + - name: foo + tablespace: bar + + # Rename the database foo to bar. + # If the database foo exists, it will be renamed to bar. + # If the database foo does not exist and the bar database exists, + # the module will report that nothing has changed. + # If both the databases exist, an error will be raised. + - name: "Rename the database foo to bar" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: rename + role_subject: databases + postgresql_databases: + - name: foo + target: bar +``` -### Pgadmin4 parameters: +### 7. Schemas management -Both parameters are affects only for pgadmin4 web version: +```yaml + - name: "Create a new schema with name acme in test database" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: schemas + postgresql_schemas: + - database: test + name: acme + + - name: "Create a new schema acme with a user bob who will own it" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: schemas + postgresql_schemas: + - name: acme + owner: bob + + - name: "Drop schema 'acme' with cascade" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: drop + role_subject: schemas + postgresql_schemas: + - name: acme + cascade_drop: true +``` -| Variable | Default | Comment | -|------------------|---------------------|------------------------------------------------------| -| pgadmin_email | my.name@company.com | pgadmin4 email for administrator login via web UI | -| pgadmin_password | my_password | pgadmin4 password for administrator login via web UI | +### 8. Privileges management -### PostgreSQL management parameters: +```yaml + # On database "library": + # GRANT SELECT, INSERT, UPDATE ON TABLE public.books, public.authors + # TO librarian, reader WITH GRANT OPTION + - name: "Grant privs to librarian and reader on database library" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + privs: SELECT,INSERT,UPDATE + type: table + objs: books,authors + schema: public + roles: librarian,reader + grant_option: true + + - name: "Same as above leveraging default values" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + privs: SELECT,INSERT,UPDATE + objs: books,authors + roles: librarian,reader + grant_option: true + + # REVOKE GRANT OPTION FOR INSERT ON TABLE books FROM reader + # Note that role "reader" will be *granted* INSERT privilege itself if this + # isn't already the case (since state: present). + - name: "Revoke privs from reader" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + priv: INSERT + obj: books + role: reader + grant_option: false + + # "public" is the default schema. This also works for PostgreSQL 8.x. + - name: "REVOKE INSERT, UPDATE ON ALL TABLES IN SCHEMA public FROM reader" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: revoke + role_subject: privileges + postgresql_privileges: + - database: library + privs: INSERT,UPDATE + objs: ALL_IN_SCHEMA + role: reader + + - name: "GRANT ALL PRIVILEGES ON SCHEMA public, math TO librarian" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + privs: ALL + type: schema + objs: public,math + role: librarian + + # Note the separation of arguments with colons. + - name: "GRANT ALL PRIVILEGES ON FUNCTION math.add(int, int) TO librarian, reader" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + privs: ALL + type: function + obj: add(int:int) + schema: math + roles: librarian,reader + + # Note that group role memberships apply cluster-wide and therefore are not + # restricted to database "library" here. + - name: "GRANT librarian, reader TO alice, bob WITH ADMIN OPTION" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + type: group + objs: librarian,reader + roles: alice,bob + admin_option: true + + # Note that here "db: postgres" specifies the database to connect to, not the + # database to grant privileges on (which is specified via the "objs" param) + - name: "GRANT ALL PRIVILEGES ON DATABASE library TO librarian" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: postgres + privs: ALL + type: database + obj: library + role: librarian + + # If objs is omitted for type "database", it defaults to the database + # to which the connection is established + - name: "GRANT ALL PRIVILEGES ON DATABASE library TO librarian" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + privs: ALL + type: database + role: librarian + + # Objs must be set, ALL_DEFAULT to TABLES/SEQUENCES/TYPES/FUNCTIONS + # ALL_DEFAULT works only with privs=ALL + # For specific + - name: "ALTER DEFAULT PRIVILEGES ON DATABASE library TO librarian" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + objs: ALL_DEFAULT + privs: ALL + type: default_privs + role: librarian + grant_option: true + + # Objs must be set, ALL_DEFAULT to TABLES/SEQUENCES/TYPES/FUNCTIONS + # ALL_DEFAULT works only with privs=ALL + # For specific + - name: "ALTER DEFAULT PRIVILEGES ON DATABASE library TO reader, step 1" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + objs: TABLES,SEQUENCES + privs: SELECT + type: default_privs + role: reader + + - name: "ALTER DEFAULT PRIVILEGES ON DATABASE library TO reader, step 2" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + objs: TYPES + privs: USAGE + type: default_privs + role: reader + + - name: "GRANT ALL PRIVILEGES ON FOREIGN DATA WRAPPER fdw TO reader" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: test + objs: fdw + privs: ALL + type: foreign_data_wrapper + role: reader + + # Available since community.postgresql 0.2.0 + - name: "GRANT ALL PRIVILEGES ON TYPE customtype TO reader" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: test + objs: customtype + privs: ALL + type: type + role: reader + + - name: "GRANT ALL PRIVILEGES ON FOREIGN SERVER fdw_server TO reader" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: test + objs: fdw_server + privs: ALL + type: foreign_server + role: reader + + # Grant 'execute' permissions on all functions in schema 'common' to role 'caller' + - name: "GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA common TO caller" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - type: function + privs: EXECUTE + roles: caller + objs: ALL_IN_SCHEMA + schema: common + + # Available since collection version 1.3.0 + # Grant 'execute' permissions on all procedures in schema 'common' to role 'caller' + # Needs PostreSQL 11 or higher and community.postgresql 1.3.0 or higher + - name: "GRANT EXECUTE ON ALL PROCEDURES IN SCHEMA common TO caller" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - type: prucedure + privs: EXECUTE + roles: caller + objs: ALL_IN_SCHEMA + schema: common + + # ALTER DEFAULT PRIVILEGES FOR ROLE librarian IN SCHEMA library GRANT SELECT ON TABLES TO reader + # GRANT SELECT privileges for new TABLES objects created by librarian as + # default to the role reader. + # For specific + - name: "ALTER privs" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: library + schema: library + objs: TABLES + privs: SELECT + type: default_privs + role: reader + target_roles: librarian + + # ALTER DEFAULT PRIVILEGES FOR ROLE librarian IN SCHEMA library REVOKE SELECT ON TABLES FROM reader + # REVOKE SELECT privileges for new TABLES objects created by librarian as + # default from the role reader. + # For specific + - name: "ALTER privs" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: revoke + role_subject: privileges + postgresql_privileges: + - database: library + schema: library + objs: TABLES + privs: SELECT + type: default_privs + role: reader + target_roles: librarian + + # Available since community.postgresql 0.2.0 + - name: "Grant type privileges for pg_catalog.numeric type to alice" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - type: type + roles: alice + privs: ALL + objs: numeric + schema: pg_catalog + database: acme + + - name: "Alter default privileges grant usage on schemas to datascience" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: grant + role_subject: privileges + postgresql_privileges: + - database: test + type: default_privs + privs: usage + objs: schemas + role: datascience +``` -#### User (role) management. +### 9. Slots management -* **postgresql_users** (list of dicts). List of postgresql users (roles) parameters to perform role action (create, -alter or drop) from database instance (see also -[postgresql_user module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_user_module.html)). -Defaults: ```yaml - - name: username - password: my_password + - name: "Create physical_one physical slot if doesn't exist" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: slots + postgresql_slots: + - name: physical_one + database: ansible + become_user: postgres + + - name: "Remove physical_one slot if exists" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: drop + role_subject: slots + postgresql_slots: + - name: physical_one + database: ansible + become_user: postgres + + - name: "Create logical_one logical slot to the database acme if doesn't exist" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: create + role_subject: slots + postgresql_slots: + - name: logical_slot_one + slot_type: logical + output_plugin: custom_decoder_one + database: "acme" + + - name: "Remove logical_one slot if exists from the cluster running on another host and non-standard port" + ansible.builtin.include_role: + name: common.linux.postgresql + vars: + role_action: drop + role_subject: slots + postgresql_slots: + - name: logical_one + login_host: mydatabase.example.org + port: 5433 + login_user: ourSuperuser + login_password: thePassword ``` +## Role Variables + +### Role parameters + +| Variable | Default | Comment | +|--------------------------------|---------|------------------------------------------------------------------------------------------------------------------------| +| role_action | install | Role action: uninstall, install, configure, create, grant, drop, revoke, dump, rename, restore | +| role_subject | server | Role subject to perform with: server, pgadmin, hba_conf, postgresql_conf, users, databases, privileges, schemas, slots | +| clean_install | true | Perform clean install | +| postgresql_version | 15 | Version of pgsql repository | +| cleanup_data_directory | true | Clean-up PostgreSQL data directory | +| postgresql_recommended_version | false | Install recommended version for current Linux distribution (1) | +| postgresql_additional_packages | [] | List of additional PostgreSQL related packages to install (2) | +| install_psycopg2 | true | Install [psycopg2](https://pypi.org/project/psycopg2/) | +| install_pgadmin | false | Install [pgadmin4](https://www.pgadmin.org/) for web mode alongside with postgresql server | +| pgadmin_installation_type | web | pgadmin installation type: web or desktop. Leave them empty to install both web and desktop. | +| firewall_control | true | Add or remove firewalld and/or ufw rules on install or uninstall. Will be skipped when firewall disabled. | + + +- (1) Recommended version install based on distribution repository or + [dnf modules](https://docs.fedoraproject.org/en-US/modularity/using-modules/). Useful when the current version of + PostgreSQL server instance is not available for your Linux distribution (e.g. check + [RedHat repository](https://www.postgresql.org/download/linux/redhat/)). + +- (2) List of additional PostgreSQL related packages, e.g: 'postgresql-contrib' or 'postgresql14-contrib' for + `postgresql_recommended_version: true` (explore what packages available + [here](https://www.postgresql.org/download/linux/)). There is no automated version handling in this list, include + versions to package names. + +### PostgreSQL server (or database instance) parameters + +- **postgresql_default_timezone**. PostgreSQL timezone. Required for PostgreSQL v14+, especially for init server + instance data directory on Alpine Linux. You can change it later, e.g: `SET TIME ZONE 'America/Montreal';` and/or add: + `timezone: 'America/Montreal'` to `postgresql_conf` dict variable (See also a + [list of timezone names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). Defaults: 'Europe/Moscow' + +- **postgresql_conf** (dict). Parameters from postgresql.conf with the same name here (see + [documentation](https://www.postgresql.org/docs/current/config-setting.html)). Double quotes to keep single + `'quotes of value'`. Defaults: + + ```yaml + port: 5432 + max_connections: 100 + superuser_reserved_connections: 3 + listen_addresses: "'*'" + ``` + +- **pg_conf_content_mode** (string). `pg_hba.conf` write content mode to perform configure hba_conf (see + [documentation](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)): `regex` (ensure line(s) presents) or + `block` (replace original file with), otherwise set template filename here (from /templates sub-folder) or full path + to replace with (e.g. `pg_hba.conf.j2`). Defaults: `pg_hba.conf.j2` + +- **hba_conf_content** (string). pg_hba.conf block or lines for regex mode. Defaults: `''` + +### Pgadmin4 parameters + +Both parameters are affected only for a pgadmin4 web version: + +| Variable | Default | Comment | +|------------------|-----------------------|------------------------------------------------------| +| pgadmin_email | | pgadmin4 email for administrator login via web UI | +| pgadmin_password | my_password | pgadmin4 password for administrator login via web UI | + +### PostgreSQL management parameters + +#### User (role) management + +- **postgresql_users** (list of dicts). List of postgresql users (roles) parameters to perform role action (create, + alter or drop) from database instance (see also + [postgresql_user module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_user_module.html)). + Defaults: + + ```yaml + - name: username + password: my_password + ``` + + | Parameter | Type | Default | Comment | |---------------------|-----------|---------|-------------------------------------------------------------------------------------------| | name | mandatory | | Name of the user (role) to add or remove. | -| comment | optional | (omit) | Adds a comment on the user (equivalent to the COMMENT ON ROLE statement) | +| comment | optional | (omit) | Adds a comment on the user (equivalent to the COMMENT ON ROLE statement) | | password | optional | (omit) | Set the user's password | | conn_limit | optional | (omit) | Specifies the user (role) connection limit. | | no_password_changes | optional | false | If true, does not inspect the database for password changes (1) | @@ -899,99 +929,108 @@ Defaults: | ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server (4) | | ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) certificate(s) (5) | | trust_input | optional | true | It makes sense to use false only when SQL injections through the options are possible (6) | - -* (1) If true, does not inspect the database for password changes. If the user already exists, skips all password -related checks. Useful when `pg_authid` is not accessible (such as in AWS RDS). Otherwise, makes password changes as -necessary. -* (2) You can specify an unhashed password, and PostgreSQL ensures the stored password is hashed when `encrypted=true` -is set. If you specify a hashed password, the module uses it as-is, regardless of the setting of encrypted. Note: -Postgresql 10 and newer does not support unhashed passwords. -* (3) Note that `[NO]CREATEUSER` is deprecated. To create a simple role for using it like a group, use `NOLOGIN` flag. -See the full list of supported flags in documentation for your PostgreSQL version. -* (4) See [libpq C Library](https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more -information on the modes. Default of prefer matches libpq default. Choices: "allow", "disable", "prefer", "require", -"verify-ca", "verify-full". -* (5) If the file exists, verifies that the server's certificate is signed by one of these authorities. -* (6) If false, checks whether values of options name, password, privs, expires, role_attr_flags, groups, comment, -session_role are potentially dangerous. - -#### Database management. - -* **postgresql_databases** (list of dicts). List of postgresql databases parameters to perform role action: create, -drop, dump, rename, restore (see also -[postgresql_db module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_db_module.html)). -Defaults: -```yaml - - name: db_name - owner: username -``` - + + +- (1) If true, do not inspect the database for password changes. If the user already exists, skip all password-related + checks. Useful when `pg_authid` is not accessible (such as in AWS RDS). Otherwise, makes password changes as + necessary. +- (2) You can specify an unhashed password, and PostgreSQL ensures the stored password is hashed when `encrypted=true` + is set. If you specify a hashed password, the module uses it as-is, regardless of the setting of encrypted. Note: + Postgresql 10 and newer does not support unhashed passwords. +- (3) Note that `[NO]CREATEUSER` is deprecated. To create a simple role for using it like a group, use `NOLOGIN` flag. + See the full list of supported flags in documentation for your PostgreSQL version. +- (4) See [libpq C Library](https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more + information on the modes. Default of prefer matches libpq default. Choices: "allow", "disable", "prefer", "require", + "verify-ca", "verify-full". +- (5) If the file exists, verifies that the server's certificate is signed by one of these authorities. +- (6) If false, checks whether values of options name, password, privs, expires, role_attr_flags, groups, comment, + session_role are potentially dangerous. + +#### Database management + +- **postgresql_databases** (list of dicts). List of postgresql databases parameters to perform role action: create, + drop, dump, rename, restore (see also + [postgresql_db module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_db_module.html)). + Defaults: + + ```yaml + - name: db_name + owner: username + ``` + + | Parameter | Type | Default | Comment | |-----------------|-----------|---------|------------------------------------------------------------------------------| | name | mandatory | | Name of the database to add or remove | - | owner | optional | '' | Name of the role to set as owner of the database | - | encoding | optional | (omit) | Encoding of the database | - | lc_collate | optional | (omit) | Collation order (LC_COLLATE) to use in the database (1) | - | lc_ctype | optional | (omit) | Specifies the database connection limit | - | template | optional | '' | Template used to create the database | - | conn_limit | optional | (omit) | Specifies the database connection limit | - | tablespace | optional | '' | The tablespace to set for the database (2) | - | target | optional | '' | File to back up or restore from. Used when role_action is dump or restore | - | target_opts | optional | '' | Additional arguments for pg_dump or restore program (3) | - | dump_extra_args | optional | (omit) | Provides additional arguments when role_action is `dump` (4) | - | ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server (5) | - | ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) (6) | - | trust_input | optional | true | It makes sense only when SQL injections through the options are possible (7) | - -* (1) Collation order (LC_COLLATE) to use in the database must match collation order of a template database unless -`template0` is used as template. -* (2) The tablespace to set for the database (see -[documentation](https://www.postgresql.org/docs/current/sql-alterdatabase.html)). If you want to move the database back -to the default tablespace, explicitly set this to pg_default. -* (3) Additional arguments for pg_dump or restore program (pg_restore or psql, depending on target's format). Used when -role_action is `dump` or `restore`. -* (4) Cannot be used with dump-file-format-related arguments like `–format=d`. -* (5) Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. See -[libpq-ssl documentation] for more information on the modes. Default of `prefer` matches libpq default. Choices: -"allow", "disable", "prefer", "require", "verify-ca", "verify-full". -* (6) The name of a file containing SSL certificate authority (CA) certificate(s). If the file exists, the server's -certificate will be verified to be signed by one of these authorities. -* (7) If `false`, check whether values of parameters owner, conn_limit, encoding, db, template, tablespace, -session_role are potentially dangerous. It makes sense to use `false` only when SQL injections via the parameters are -possible. - -#### Schema management. - -* **postgresql_schemas** (list of dicts). List of parameters to add or remove schemas (see also -[postgresql_schema module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_schema_module.html)). -Defaults: -```yaml - - name: schema_name - database: db_name - owner: username -``` - +| owner | optional | '' | Name of the role to set as owner of the database | +| encoding | optional | (omit) | Encoding of the database | +| lc_collate | optional | (omit) | Collation order (LC_COLLATE) to use in the database (1) | +| lc_ctype | optional | (omit) | Specifies the database connection limit | +| template | optional | '' | Template used to create the database | +| conn_limit | optional | (omit) | Specifies the database connection limit | +| tablespace | optional | '' | The tablespace to set for the database (2) | +| target | optional | '' | File to back up or restore from. Used when role_action is dump or restore | +| target_opts | optional | '' | Additional arguments for pg_dump or restore program (3) | +| dump_extra_args | optional | (omit) | Provides additional arguments when role_action is `dump` (4) | +| ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server (5) | +| ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) (6) | +| trust_input | optional | true | It makes sense only when SQL injections through the options are possible (7) | + + +- (1) Collation order (LC_COLLATE) to use in the database must match collation order of a template database unless + `template0` is used as template. +- (2) The tablespace to set for the database (see + [documentation](https://www.postgresql.org/docs/current/sql-alterdatabase.html)). If you want to move the database back + to the default tablespace, explicitly set this to pg_default. +- (3) Additional arguments for pg_dump or restore program (pg_restore or psql, depending on target's format). Used when + role_action is `dump` or `restore`. +- (4) Cannot be used with dump-file-format-related arguments like `–format=d`. +- (5) Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. See + [libpq-ssl documentation] for more information on the modes. Default of `prefer` matches libpq default. Choices: + "allow", "disable", "prefer", "require", "verify-ca", "verify-full". +- (6) The name of a file containing SSL certificate authority (CA) certificate(s). If the file exists, the server's + certificate will be verified to be signed by one of these authorities. +- (7) If `false`, check whether values of parameters owner, conn_limit, encoding, db, template, tablespace, + session_role are potentially dangerous. It makes sense to use `false` only when SQL injections via the parameters are + possible. + +#### Schema management + +- **postgresql_schemas** (list of dicts). List of parameters to add or remove schemas (see also + [postgresql_schema module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_schema_module.html)). + Defaults: + + ```yaml + - name: schema_name + database: db_name + owner: username + ``` + + | Parameter | Type | Default | Comment | |--------------|-----------|----------|---------------------------------------------------------------------------------------| | name | mandatory | | Name of the schema to add or remove | - | cascade_drop | optional | (omit) | Drop schema with CASCADE to remove child objects. Choices: false/true | - | database | optional | postgres | Name of the database to connect to and add or remove the schema | - | owner | optional | (omit) | Name of the role to set as owner of the schema | - | ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server | - | ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) certificate(s) | - | trust_input | optional | true | It makes sense only when SQL injections through the options are possible | +| cascade_drop | optional | (omit) | Drop schema with CASCADE to remove child objects. Choices: false/true | +| database | optional | postgres | Name of the database to connect to and add or remove the schema | +| owner | optional | (omit) | Name of the role to set as owner of the schema | +| ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server | +| ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) certificate(s) | +| trust_input | optional | true | It makes sense only when SQL injections through the options are possible | + -#### Privileges management. +#### Privileges management -* **postgresql_privileges** (list of dicts). List of privileges to grant or revoke on database objects (see also +- **postgresql_privileges** (list of dicts). List of privileges to grant or revoke on database objects (see also [postgresql_privs module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_privs_module.html)). Defaults: -```yaml - - database: db_name - roles: username - privs: ALL -``` + ```yaml + - database: db_name + roles: username + privs: ALL + ``` + + | Parameter | Type | Default | Comment | |--------------|-----------|----------|------------------------------------------------------------------------------------------| | database | mandatory | | Name of database to connect to | @@ -1001,36 +1040,39 @@ Defaults: | privs | optional | (omit) | Comma separated list of privileges to grant/revoke | | schema | optional | (omit) | Schema that contains the database objects specified via objs | | target_roles | optional | (omit) | A list of existing role names to set as the default permissions for database objects (4) | - | type | optional | (omit) | Type of database object to set privileges on (5) | - | ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server | - | ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) certificate(s) | - | trust_input | optional | true | It makes sense only when SQL injections through the options are possible | - -* (1) The special value `PUBLIC` can be provided instead to set permissions for the implicitly defined PUBLIC group. -* (2) Set to `false` to revoke GRANT OPTION, leave unspecified to make no changes. grant_option only has an effect if -`role_action` is `grant`. Choices: `true`, `false`. -* (3) If type is `table`, `partition table`, `sequence`, `function` or `procedure`, the special value `ALL_IN_SCHEMA` -can be provided instead to specify all database objects of type in the schema specified via schema. (This also works -with PostgreSQL < 9.0). `procedure` is supported since PostgreSQL 11 and community.postgresql collection 1.3.0. If type -is `database`, this parameter can be omitted, in which case privileges are set for the database specified via -*database*. If type is `function` or `procedure`, colons (":") in object names will be replaced with commas (needed to -specify signatures, see examples). -* (4) A list of existing role (user/group) names to set as the default permissions for database objects subsequently -created by them. Parameter *target_roles* is only available with `type=default_privs`. -* (5) The `type` choice is available since Ansible version 2.10. The `procedure` is supported since collection version -1.3.0 and PostgreSQL 11. Choices: "database", "default_privs", "foreign_data_wrapper", "foreign_server", "function", -"group", "language", "table" (default), "tablespace", "schema", "sequence", "type", "procedure". - -#### Slots management. - -* **postgresql_slots** (list of dicts). List of parameters to add or remove replication slots from a database (see also -[postgresql_slot module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_slot_module.html)). -Defaults: -```yaml - - name: physical_slot_one - db: db_name -``` - +| type | optional | (omit) | Type of database object to set privileges on (5) | +| ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server | +| ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) certificate(s) | +| trust_input | optional | true | It makes sense only when SQL injections through the options are possible | + + +- (1) The special value `PUBLIC` can be provided instead to set permissions for the implicitly defined PUBLIC group. +- (2) Set to `false` to revoke GRANT OPTION, leave unspecified to make no changes. grant_option only has an effect if + `role_action` is `grant`. Choices: `true`, `false`. +- (3) If type is `table`, `partition table`, `sequence`, `function` or `procedure`, the special value `ALL_IN_SCHEMA` + can be provided instead to specify all database objects of type in the schema specified via schema. (This also works + with PostgreSQL < 9.0). `procedure` is supported since PostgreSQL 11 and community.postgresql collection 1.3.0. If + type is `database`, this parameter can be omitted, in which case privileges are set for the database specified via + *database*. If type is `function` or `procedure`, colons (":") in object names will be replaced with commas (needed to + specify signatures, see examples). +- (4) A list of existing role (user/group) names to set as the default permissions for database objects subsequently + created by them. Parameter *target_roles* is only available with `type=default_privs`. +- (5) The `type` choice is available since Ansible version 2.10. The `procedure` is supported since collection version + 1.3.0 and PostgreSQL 11. Choices: "database", "default_privs", "foreign_data_wrapper", "foreign_server", "function", + "group", "language", "table" (default), "tablespace", "schema", "sequence", "type", "procedure". + +#### Slots management + +- **postgresql_slots** (list of dicts). List of parameters to add or remove replication slots from a database (see also + [postgresql_slot module documentation](https://docs.ansible.com/ansible/latest/collections/community/postgresql/postgresql_slot_module.html)). + Defaults: + + ```yaml + - name: physical_slot_one + db: db_name + ``` + + | Parameter | Type | Default | Comment | |---------------------|-----------|----------|--------------------------------------------------------------------------------------------| | name | mandatory | | Name of the replication slot to add or remove | @@ -1038,18 +1080,18 @@ Defaults: | immediately_reserve | optional | false | Specifies that the LSN slot be reserved immediately, otherwise on the first connection (1) | | slot_type | optional | physical | Slot type: logical or physical | | output_plugin | optional | (omit) | All logical slots must indicate which output plugin decoder they're using (2) | - | ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server | - | ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) certificate(s) | - | trust_input | optional | true | It makes sense only when SQL injections through the options are possible | +| ssl_mode | optional | prefer | Determines how an SSL session is negotiated with the server | +| ca_cert | optional | '' | Specifies the name of a file containing SSL certificate authority (CA) certificate(s) | +| trust_input | optional | true | It makes sense only when SQL injections through the options are possible | + -* (1) Optional parameter that when `true` specifies that the LSN for this replication slot be reserved immediately, -otherwise the default, `false`, specifies that the LSN is reserved on the first connection from a streaming replication -client. Is available from PostgreSQL version 9.6. Uses only with *slot_type=physical*. Mutually exclusive with -*slot_type=logical*. -* (2) This parameter does not apply to physical slots. It will be ignored with *slot_type=physical*. If it wasn't set -(ommited) *"test_decoding"* will be set by default. +- (1) Optional parameter that when `true` specifies that the LSN for this replication slot be reserved immediately, + otherwise the default, `false`, specifies that the LSN is reserved on the first connection from a streaming + replication client. It Is available from PostgreSQL version 9.6. Uses only with *slot_type=physical*. Mutually + exclusive with *slot_type=logical*. +- (2) This parameter does not apply to physical slots. It will be ignored with *slot_type=physical*. If it wasn't set + (omitted) *"test_decoding"* will be set by default. -License -------- +## License -MIT-0 +BSD 3-Clause License diff --git a/roles/zabbix_agent/.ansible-lint b/roles/zabbix_agent/.ansible-lint index a6a88e0..e1f738c 100644 --- a/roles/zabbix_agent/.ansible-lint +++ b/roles/zabbix_agent/.ansible-lint @@ -1,21 +1,12 @@ --- -### ansible linter config -### -### more details: -### - https://ansible-lint.readthedocs.io/en/latest/configuring/#configuration-file -### Please keep in mind how to skip rule inside a playbook/role: -### - https://ansible-lint.readthedocs.io/en/latest/rules/#false-positives-skipping-rules +# ansible-lint config +# see: https://ansible.readthedocs.io/projects/lint/usage/#specifying-rules-at-runtime +# https://ansible.readthedocs.io/projects/lint/usage/#muting-warnings-to-avoid-false-positives -exclude_paths: - - .idea/ - - .git/ - - .scripts/ - - .gilab-ci.yml - - .gitignore - - .gitmodules quiet: true verbosity: 1 +# exclude_paths: # skip_list: # enable_list: # warn_list: diff --git a/roles/zabbix_agent/.yamllint b/roles/zabbix_agent/.yamllint index b45b2f6..08631a5 100644 --- a/roles/zabbix_agent/.yamllint +++ b/roles/zabbix_agent/.yamllint @@ -7,7 +7,10 @@ ignore: | rules: braces: + min-spaces-inside: 0 max-spaces-inside: 1 + min-spaces-inside-empty: 0 + max-spaces-inside-empty: 0 level: error brackets: max-spaces-inside: 1 @@ -20,7 +23,7 @@ rules: level: error comments: disable comments-indentation: disable - document-start: disable + document-start: enable empty-lines: max: 2 level: error @@ -37,4 +40,4 @@ rules: trailing-spaces: enable truthy: allowed-values: ['true', 'false'] - check-keys: true + check-keys: true \ No newline at end of file diff --git a/roles/zabbix_agent/README.md b/roles/zabbix_agent/README.md index eef4644..4aaefe0 100644 --- a/roles/zabbix_agent/README.md +++ b/roles/zabbix_agent/README.md @@ -1,80 +1,80 @@ -zabbix_agent -========= +# zabbix_agent + This role installs zabbix agent and configures them for services, apps and platform autodiscovery on [Zabbix Server side](#setup-on-zabbix-server-side). -Preamble --------- +## Preamble + Zabbix server can detect applications, services, platforms and virtualization by a special hash value (see autodiscovery hashes) predefined in a Zabbix agent configuration file. For example: -``` +```text UserParameter=hostmetadata,echo 'Linux ff6e6f6e65 dd6a617661' ``` When Zabbix Server tries to discover hosts like this one, the next step is following: add the host to a specified -group (like Web servers, Cloud nodes, etc) and apply template to monitoring filesystems (ZFS, btrfs, mdadm), -application (nginx, etc), virtualization or containerization and other hardware and software platforms. +group (like Web servers, Cloud nodes, etc.) and apply template to monitoring filesystems (ZFS, btrfs, mdadm), +application (nginx, etc.), virtualization or containerization and other hardware and software platforms. + +## Requirements -Requirements ------------- - **Zabbix version.** Written for Zabbix 5.0 automation, but probably works for other versions of Zabbix agent. Before - you setup please confirm a package version is available for your version of Linux distribution visiting + you set up please confirm a package version is available for your version of Linux distribution visiting [Zabbix download page](https://www.zabbix.com/download?zabbix=5.0) or directly [repository](https://repo.zabbix.com/zabbix/). - **Supported Linux distribution**. Works only with x86_64 architecture: - - **Ubuntu: 14.04, 16.04, 18.04, 20.04, 22.04**. Perhaps this role also works on Non-LTS or older versions, but - wasn't tested. - - **Debian: 8, 9, 10, 11, 12**. Perhaps this role also works on another version of Debian distro, but wasn't tested. - - **RHEL: 6, 7, 8, 9**. Perhaps this role also works on older versions of RHEL distro, but tested on CentOS and - Oracle Linux distributions. - - **Alpine Linux: 3.18**. Perhaps this role also works on another version of distro, but wasn't tested. - - Other Linux distributions, Windows, Solaris, FreeBSD, AIX and armv7/aarch64 architectures aren't supported. + - **Ubuntu: 14.04, 16.04, 18.04, 20.04, 22.04**. Perhaps this role also works on Non-LTS or older versions, but + wasn't tested. + - **Debian: 8, 9, 10, 11, 12**. Perhaps this role also works on another version of Debian distro, but wasn't tested. + - **RHEL: 6, 7, 8, 9**. Perhaps this role also works on older versions of RHEL distro, but tested on CentOS and + Oracle Linux distributions. + - **Alpine Linux: 3.18**. Perhaps this role also works on another version of distro, but wasn't tested. + - Other Linux distributions, Windows, Solaris, FreeBSD, AIX and armv7/aarch64 architectures aren't supported. - **Zabbix agent configuration**. Platforms discovery uses additional packages (like ipmitool), other platforms and -services detects by binary files search, but the most of the services detects by their enabled systemd daemons -(`systemctl is-enabled` command) or rc-service (Alpine linux). So daemons autodiscovery works only on linux distros with -systemd. Already installed Zabbix agent re-configuration (check `customize_agent_only` in -[Role Variables](#role-variables) using this role also possible). + services detects by binary files search, but the most of the services detects by their enabled systemd daemons + (`systemctl is-enabled` command) or rc-service (Alpine linux). So daemons autodiscovery works only on linux distros + with systemd. Already installed Zabbix agent re-configuration (check `customize_agent_only` in + [Role Variables](#role-variables) using this role also possible). + +## Dependencies -Dependencies ------------- - [pacman module](https://docs.ansible.com/ansible/latest/collections/community/general/pacman_module.html) -from community.general; + from community.general; - `xxd` or `vim-common`, `wget` and `policycoreutils-python` packages (will be automatically installed on supported -Linux distributions, otherwise install them manually); + Linux distributions, otherwise install them manually); - `sudo` package on Debian systems installed via 'netinstall' source or docker images. -Role Variables --------------- -Main parameters: - -| Variable | default | Comment | -|-----------------------------|----------------------------------------|------------------------------------------------------------------------| -| `zabbix_release` | 5.0 | Zabbix release (not effective for Alpine) | -| `install_v2_agent` | true | Install Zabbix agent v2 when possible, otherwise install v1 | -| `customize_agent` | true | Configure agent for automatic services discovery and templates add | -| `clean_install` | true | Perform clean install (re-install agent with clean-up) | -| `conf_with_dir_clean` | true | Configure or perform clean installation with config directory clean-up | -| `debug_mode` | true | More outputs | -| `customize_agent_only` | false | Re-configure agent without Zabbix install | -| `zabbix_repo_url` | http://repo.zabbix.com | Zabbix repo URL | -| `archlinux_repo_url_prefix` | https://archive.archlinux.org/packages | Archlinux repo URL prefix | -| `repo_dl_validate_certs` | false | Check certificates on Zabbix repo package download (required on | -| | | outdated virtual machines snapshots) | +## Role Variables +Main parameters: + +| Variable | default | Comment | +|-----------------------------|------------------------------------------|------------------------------------------------------------------------| +| `zabbix_release` | 5.0 | Zabbix release (not effective for Alpine) | +| `install_v2_agent` | true | Install Zabbix agent v2 when possible, otherwise install v1 | +| `customize_agent` | true | Configure agent for automatic services discovery and templates add | +| `clean_install` | true | Perform clean install (re-install agent with clean-up) | +| `conf_with_dir_clean` | true | Configure or perform clean installation with config directory clean-up | +| `debug_mode` | true | More outputs | +| `customize_agent_only` | false | Re-configure agent without Zabbix install | +| `zabbix_repo_url` | | Zabbix repo URL | +| `archlinux_repo_url_prefix` | | Archlinux repo URL prefix | +| `repo_dl_validate_certs` | false | Check certificates on Zabbix repo package download (required on | +| | | outdated virtual machines snapshots) | + Zabbix agent settings: -| Parameter | Default | Comment | -|----------------------------|-------------------------------|---------------------------------| -| `remote_cmd_key` | EnableRemoteCommands | Enable remote commands key name | -| `remote_cmd_value` | 1 | Enable remote commands value | -| `logfile_size_key` | LogFileSize | Logfile size key name | -| `logfile_size_value` | 100 | Logfile size value | -| `zabbix_servers_passive` | 10.0.0.1,10.0.0.2 | Zabbix server IP passive checks | -| `zabbix_servers_active` | 10.0.0.1:10051,10.0.0.2:10051 | Zabbix server IP active checks | -| `zabbix_host_metadata` | Linux | Zabbix host metadata | +| Parameter | Default | Comment | +|----------------------------|----------------------|---------------------------------| +| `remote_cmd_key` | EnableRemoteCommands | Enable remote commands key name | +| `remote_cmd_value` | 1 | Enable remote commands value | +| `logfile_size_key` | LogFileSize | Logfile size key name | +| `logfile_size_value` | 100 | Logfile size value | +| `zabbix_servers_passive` | 10.0.1.47 | Zabbix server IP passive checks | +| `zabbix_servers_active` | 10.0.1.47:10051 | Zabbix server IP active checks | +| `zabbix_host_metadata` | Linux | Zabbix host metadata | There are also agent settings related variables like `zabbix_agent_conf_name` or`zabbix_agent_binary`, but changing them is useless. This is for Zabbix agents versions differences discovery. @@ -85,9 +85,12 @@ Autodiscovery hashes: |-----------------------|-------------------------|-----------------------------------------------| | openvpn_bin | dd6f76706e | Openvpn binary discovery | | java_bin | dd6a617661 | Java platform binary discovery | +| emzbuilder_bin | dd65627362 | EmziOS builder binary discovery | | mysql | dd6d7973716c | MySQL daemon discovery | | postgresql | dd706773716c | PostgreSQL daemon discovery | | openvpn | dd6f76706e | Openvpn daemon discovery | +| cloudstack_agent | dd637361676e74 | Apache Cloudstack agent daemon discovery | +| cloudstack_management | dd63736d676d74 | Apache Cloudstack management daemon discovery | | bareos_fd | dd6272736664 | Bareos File Daemon discovery | | bareos_dir | dd627273646972 | Bareos Director Daemon discovery | | bareos_sd | dd6272737364 | Bareos Storage Daemon discovery | @@ -113,164 +116,179 @@ Autodiscovery hashes: | | ee416476616e74656368 | Advantech(tm) hardware platform disovery | | | ee | hardware platform disovery | -Example Playbook ----------------- +## Example Playbook Install and configure Zabbix v1 agent(s): - - hosts: all - become: true - become_method: sudo - roles: - - role: alexanderbazhenoff.linux.zabbix_agent - install_v2_agent: false +```yaml +- hosts: all + become: true + become_method: sudo + roles: + - role: zabbix_agent + install_v2_agent: false +``` Install and configure Zabbix v2 agent(s): - - hosts: all - become: true - become_method: sudo - roles: - - role: alexanderbazhenoff.linux.zabbix_agent - install_v2_agent: true +```yaml +- hosts: all + become: true + become_method: sudo + roles: + - role: zabbix_agent + install_v2_agent: true +``` Perform re-configuration of already installed Zabbix agent(s): - - hosts: all - become: true - become_method: sudo - roles: - - role: alexanderbazhenoff.linux.zabbix_agent - customize_agent_only: true +```yaml +- hosts: all + become: true + become_method: sudo + roles: + - role: zabbix_agent + customize_agent_only: true +``` + +## Setup on Zabbix Server side -Setup on Zabbix Server side ---------------------------- To make services, platforms and apps discovery working on Zabbix Server side, you should perform additional settings: 1. Open `Configuration -> Discovery` on Zabbix Server Web UI. Select your discovery rule for network IP range then -add `Zabbix agent "hostmetadata"` to "Checks". After successful Zabbix agent reconfiguration using this role you'll see -`hostmetadata` column in the "Status of discovery" (`Monitoring -> Discovery` on Zabbix Server Web UI). Just wait for -some minutes for IP range scan. + add `Zabbix agent "hostmetadata"` to "Checks". After successful Zabbix agent reconfiguration using this role you'll + see `hostmetadata` column in the "Status of discovery" (`Monitoring -> Discovery` on Zabbix Server Web UI). Wait for + some minutes for IP range scan. 2. Open `Configuration -> Actions -> Dicovery actions` in Zabbix Server Web UI and create your rule for `hostmetadata` -tag. You wish to create "MySQL - discovery on linux for Zabbix agents v1" for example: - -Action: -``` -(A and B and C) and D and E and F - -Conditions: -A Received value contains Linux -B Received value contains dd7a626131 -C Received value contains dd6d7973716c -D Uptime/Downtime is greater than or equals 3600 -E Discovery status equals Up -F Service type equals Zabbix agent - -``` -Operations: -``` -Run remote commands on current host -Add to host groups: Services/MySQL servers -Link to templates: Template DB MySQL by Zabbix agent -``` -Remote Command (Zabbix agent for current host): -``` -wget -N -O /tmp/mysql_selinux.sh http://yourzabbbix.domain/downloads/mysql/mysql_selinux.sh -bash /tmp/mysql_selinux.sh -echo "[client]" > $(getent passwd zabbix | cut -d : -f 6)/my.cnf -echo "user='zbx_monitor'" >> $(getent passwd zabbix | cut -d : -f 6)/my.cnf -echo "password='Yourpassword'" >> $(getent passwd zabbix | cut -d : -f 6)/my.cnf -chown zabbix:zabbix $(getent passwd zabbix | cut -d : -f 6)/my.cnf -wget -N -O /etc/zabbix/zabbix_agentd.d/template_db_mysql.conf http://yourzabbbix.domain/downloads/mysql/template_db_mysql.conf -wget -N -O /tmp/restart_daemon.sh http://yourzabbbix.domain/downloads/restart_daemon.sh -echo "none" > /tmp/zabbix-agent-restart.log -bash /tmp/restart_daemon.sh zabbix-agent -echo "ok" > /tmp/zabbix-agent-restart.log -``` -where you should change `yourzabbbix.domain` URL and `'Yourpassword'` password. - -The following steps are for the command execution to add template configurations and settings on Zabbix-agent side after -the service discovery. It means you didn't put them in `/etc/zabbix` or whatever before discovery on Zabbix Server. -**Otherwise, skip the next steps.** + tag. You wish to create "MySQL - discovery on linux for Zabbix agents v1" for example: + + Action: + + ```text + (A and B and C) and D and E and F + + Conditions: + A Received value contains Linux + B Received value contains dd7a626131 + C Received value contains dd6d7973716c + D Uptime/Downtime is greater than or equals 3600 + E Discovery status equals Up + F Service type equals Zabbix agent + ``` + + Operations: + + ```text + Run remote commands on current host + Add to host groups: Services/MySQL servers + Link to templates: Template DB MySQL by Zabbix agent + ``` + + Remote Command (Zabbix agent for current host): + + ```bash + wget -N -O /tmp/mysql_selinux.sh http://your.zabbix.domain/downloads/mysql/mysql_selinux.sh + bash /tmp/mysql_selinux.sh + echo "[client]" > $(getent passwd zabbix | cut -d : -f 6)/my.cnf + echo "user='zbx_monitor'" >> $(getent passwd zabbix | cut -d : -f 6)/my.cnf + echo "password='Yourpassword'" >> $(getent passwd zabbix | cut -d : -f 6)/my.cnf + chown zabbix:zabbix $(getent passwd zabbix | cut -d : -f 6)/my.cnf + wget -N -O /etc/zabbix/zabbix_agentd.d/template_db_mysql.conf http://your.zabbix.domain/downloads/mysql/template_db_mysql.conf + wget -N -O /tmp/restart_daemon.sh http://your.zabbix.domain/downloads/restart_daemon.sh + echo "none" > /tmp/zabbix-agent-restart.log + bash /tmp/restart_daemon.sh zabbix-agent + echo "ok" > /tmp/zabbix-agent-restart.log + ``` + + where you should change `yourzabbbix.domain` URL and `'Yourpassword'` password. + + The following steps are for the command execution to add template configurations and settings on Zabbix-agent side + after the service discovery. It means you didn't put them in `/etc/zabbix` or whatever before discovery on Zabbix + Server. **Otherwise, skip the next steps.** 3. Put your template available to download from Zabbix Server, e.g. -`/usr/share/zabbix/downloads/mysql/template_db_mysql.conf`: -``` -UserParameter=mysql.ping[*], mysqladmin --defaults-extra-file='/var/lib/zabbix/my.cnf' ping -UserParameter=mysql.get_status_variables[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sNX -e "show global status" -UserParameter=mysql.version[*], mysqladmin --defaults-extra-file='/var/lib/zabbix/my.cnf' version -UserParameter=mysql.db.discovery[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sN -e "show databases" -UserParameter=mysql.dbsize[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sN -e "SELECT SUM(DATA_LENGTH + INDEX_LENGTH) FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA='$3'" -UserParameter=mysql.replication.discovery[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sNX -e "show slave status" -UserParameter=mysql.slave_status[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sN -e "show slave status" -``` -4. Put your script to change Zabbix-agent selinux policies available to download from Zabbix Server (skip this step for -non-RedHat Linux distros), e.g. `/usr/share/zabbix/downloads/mysql/mysql_selinux.sh`: - -```bash -#!/usr/bin/env bash - - -if [[ -f /etc/redhat-release ]] && [[ $(sestatus | head -1 | awk '{print $3}') == "enabled" ]]; then - -cat < zabbix_home.te -module zabbix_home 1.0; - -require { - type zabbix_agent_t; - type zabbix_var_lib_t; - type mysqld_etc_t; - type mysqld_port_t; - type mysqld_var_run_t; - class file { open read }; - class tcp_socket name_connect; - class sock_file write; -} - -#============= zabbix_agent_t ============== - -allow zabbix_agent_t zabbix_var_lib_t:file read; -allow zabbix_agent_t zabbix_var_lib_t:file open; -allow zabbix_agent_t mysqld_etc_t:file read; -allow zabbix_agent_t mysqld_port_t:tcp_socket name_connect; -allow zabbix_agent_t mysqld_var_run_t:sock_file write; -EOF -checkmodule -M -m -o zabbix_home.mod zabbix_home.te -semodule_package -o zabbix_home.pp -m zabbix_home.mod -semodule -i zabbix_home.pp -restorecon -R /var/lib/zabbix - -fi -``` -5. Put your script to restart zabbix-agent daemon (to apply config change) available to download from Zabbix Server, -e.g. ` /usr/share/zabbix/downloads/restart_daemon.sh`: -``` -#!/usr/bin/env bash - + `/usr/share/zabbix/downloads/mysql/template_db_mysql.conf`: + + ```text + UserParameter=mysql.ping[*], mysqladmin --defaults-extra-file='/var/lib/zabbix/my.cnf' ping + UserParameter=mysql.get_status_variables[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sNX -e "show global status" + UserParameter=mysql.version[*], mysqladmin --defaults-extra-file='/var/lib/zabbix/my.cnf' version + UserParameter=mysql.db.discovery[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sN -e "show databases" + UserParameter=mysql.dbsize[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sN -e "SELECT SUM(DATA_LENGTH + INDEX_LENGTH) FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA='$3'" + UserParameter=mysql.replication.discovery[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sNX -e "show slave status" + UserParameter=mysql.slave_status[*], mysql --defaults-extra-file='/var/lib/zabbix/my.cnf' -sN -e "show slave status" + ``` + -SERVICE_NAME=$1 -echo "Restarting ${SERVICE_NAME}..." +4. Put your script to change Zabbix-agent selinux policies available to download from Zabbix Server (skip this step for + non-RedHat Linux distros), e.g. `/usr/share/zabbix/downloads/mysql/mysql_selinux.sh`: + + ```bash + #!/usr/bin/env bash + + if [[ -f /etc/redhat-release ]] && [[ $(sestatus | head -1 | awk '{print $3}') == "enabled" ]]; then + + cat < zabbix_home.te + module zabbix_home 1.0; + + require { + type zabbix_agent_t; + type zabbix_var_lib_t; + type mysqld_etc_t; + type mysqld_port_t; + type mysqld_var_run_t; + class file { open read }; + class tcp_socket name_connect; + class sock_file write; + } + + #============= zabbix_agent_t ============== + + allow zabbix_agent_t zabbix_var_lib_t:file read; + allow zabbix_agent_t zabbix_var_lib_t:file open; + allow zabbix_agent_t mysqld_etc_t:file read; + allow zabbix_agent_t mysqld_port_t:tcp_socket name_connect; + allow zabbix_agent_t mysqld_var_run_t:sock_file write; + EOF + checkmodule -M -m -o zabbix_home.mod zabbix_home.te + semodule_package -o zabbix_home.pp -m zabbix_home.mod + semodule -i zabbix_home.pp + restorecon -R /var/lib/zabbix + + fi + ``` -if [[ -f /bin/systemctl ]]; then - set -x - systemctl restart ${SERVICE_NAME} -else - if [[ -f /usr/sbin/service ]]; then +5. Put your script to restart zabbix-agent daemon (to apply config change) available to download from Zabbix Server, + e.g. `/usr/share/zabbix/downloads/restart_daemon.sh`: + + ```bash + #!/usr/bin/env bash + + SERVICE_NAME=$1 + echo "Restarting ${SERVICE_NAME}..." + + if [[ -f /bin/systemctl ]]; then set -x - service ${SERVICE_NAME} restart + systemctl restart ${SERVICE_NAME} else - if [[ -f /etc/init.d/${SERVICE_NAME} ]]; then + if [[ -f /usr/sbin/service ]]; then set -x - /./etc/init.d/${SERVICE_NAME} restart + service ${SERVICE_NAME} restart else - echo "Fatal error: no systemctl, or service or init.d script found for ${SERVICE_NAME}" - exit 1 + if [[ -f /etc/init.d/${SERVICE_NAME} ]]; then + set -x + /./etc/init.d/${SERVICE_NAME} restart + else + echo "Fatal error: no systemctl, or service or init.d script found for ${SERVICE_NAME}" + exit 1 + fi fi fi -fi -``` -You can also make your custom restart script based on config changes (using diff or whatever). This is just a concept. + ``` + + You can also make your custom restart script based on config changes (using diff or whatever). This is just a + concept. + +## License -License -------- -MIT-0 +BSD 3-Clause License