libretic/ansible-sshd
6
0
Fork 0
mirror of https://github.com/willshersystems/ansible-sshd synced 2024-12-17 22:20:19 +01:00
Code Issues Projects Releases Packages Wiki Activity

ci: Add markdownlint, test_converting_readme, and build_docs workflows

Browse source 
* markdownlint runs against README.md to avoid any issues with
  converting it to HTML
* test_converting_readme converts README.md > HTML and uploads this test
  artifact to ensure that conversion works fine
* build_docs converts README.md > HTML and pushes the result to the
  docs branch to publish dosc to GitHub pages site
This commit is contained in:
Sergei Petrosian 2023-08-15 15:43:21 +02:00 committed by Jakub Jelen
parent d6abe9c032
commit 625b74a2cc
7 changed files with 652 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.ansible-lint
View file

@ -1,5 +1,6 @@
exclude_paths:
- tests/roles/
- .tox/
- .markdownlint.yaml
skip_list:
- var-naming[no-role-prefix]

101
.github/workflows/build_docs.yml vendored Normal file
View file

@ -0,0 +1,101 @@
---
# yamllint disable rule:line-length
name: Convert README.md to HTML and push to docs branch
on: # yamllint disable-line rule:truthy
push:
branches:
- main
paths:
- README.md
release:
types:
- published
permissions:
contents: read
jobs:
build_docs:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Update pip, git
run: |
set -euxo pipefail
sudo apt update
sudo apt install -y git
- name: Check out code
uses: actions/checkout@v3
with:
fetch-depth: 0
- name: Ensure the docs branch
run: |
set -euxo pipefail
branch=docs
existed_in_remote=$(git ls-remote --heads origin $branch)
if [ -z "${existed_in_remote}" ]; then
echo "Creating $branch branch"
git config --global user.name "${{ github.actor }}"
git config --global user.email "${{ github.actor }}@users.noreply.github.com"
git checkout --orphan $branch
git reset --hard
git commit --allow-empty -m "Initializing $branch branch"
git push origin $branch
echo "Created $branch branch"
else
echo "Branch $branch already exists"
fi
- name: Checkout the docs branch
uses: actions/checkout@v3
with:
ref: docs
- name: Fetch README.md and .pandoc_template.html5 template from the workflow branch
uses: actions/checkout@v3
with:
sparse-checkout: |
README.md
.pandoc_template.html5
sparse-checkout-cone-mode: false
path: ref_branch
- name: Set RELEASE_VERSION based on whether run on release or on push
run: |
set -euxo pipefail
if [ ${{ github.event_name }} = release ]; then
echo "RELEASE_VERSION=${{ github.event.release.tag_name }}" >> $GITHUB_ENV
elif [ ${{ github.event_name }} = push ]; then
echo "RELEASE_VERSION=latest" >> $GITHUB_ENV
else
echo Unsupported event
exit 1
fi
- name: Ensure that version and docs directories exist
run: mkdir -p ${{ env.RELEASE_VERSION }} docs
- name: Convert README.md to HTML and save to the version directory
uses: docker://pandoc/core:latest
with:
args: >-
--from gfm --to html5 --toc --shift-heading-level-by=-1
--template ref_branch/.pandoc_template.html5
--output ${{ env.RELEASE_VERSION }}/README.html ref_branch/README.md
- name: Copy latest README.html to docs/index.html for GitHub pages
if: env.RELEASE_VERSION == 'latest'
run: cp ${{ env.RELEASE_VERSION }}/README.html docs/index.html
- name: Commit changes
run: |
git config --global user.name "${{ github.actor }}"
git config --global user.email "${{ github.actor }}@users.noreply.github.com"
git add ${{ env.RELEASE_VERSION }}/README.html docs/index.html
git commit -m "Update README.html for ${{ env.RELEASE_VERSION }}"
- name: Push changes
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: docs

34
.github/workflows/markdownlint.yml vendored Normal file
View file

@ -0,0 +1,34 @@
---
# yamllint disable rule:line-length
name: Markdown Lint
on: # yamllint disable-line rule:truthy
pull_request:
merge_group:
branches:
- main
types:
- checks_requested
push:
branches:
- main
workflow_dispatch:
permissions:
contents: read
jobs:
markdownlint:
runs-on: ubuntu-latest
steps:
- name: Update pip, git
run: |
set -euxo pipefail
sudo apt update
sudo apt install -y git
- name: Check out code
uses: actions/checkout@v3
- name: Lint README.md
uses: docker://avtodev/markdown-lint:master
with:
args: README.md
config: .markdownlint.yaml

43
.github/workflows/test_converting_readme.yml vendored Normal file
View file

@ -0,0 +1,43 @@
---
# yamllint disable rule:line-length
name: Test converting README.md to README.html
on: # yamllint disable-line rule:truthy
pull_request:
merge_group:
branches:
- main
types:
- checks_requested
push:
branches:
- main
permissions:
contents: read
jobs:
test_converting_readme:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Update pip, git
run: |
set -euxo pipefail
sudo apt update
sudo apt install -y git
- name: Check out code
uses: actions/checkout@v3
- name: Convert README.md to HTML and save to the version directory
uses: docker://pandoc/core:latest
with:
args: >-
--from gfm --to html5 --toc --shift-heading-level-by=-1
--template .pandoc_template.html5
--output README.html README.md
- name: Upload README.html as an artifact
uses: actions/upload-artifact@master
with:
name: README.html
path: README.html

260
.markdownlint.yaml Normal file
View file

@ -0,0 +1,260 @@
# Default state for all rules
default: true
# Path to configuration file to extend
extends: null
# MD001/heading-increment/header-increment - Heading levels should only increment by one level at a time
MD001: true
# MD002/first-heading-h1/first-header-h1 - First heading should be a top-level heading
MD002:
# Heading level
level: 1
# MD003/heading-style/header-style - Heading style
MD003:
# Heading style
style: "consistent"
# MD004/ul-style - Unordered list style
MD004:
# List style
style: "consistent"
# MD005/list-indent - Inconsistent indentation for list items at the same level
MD005: true
# MD006/ul-start-left - Consider starting bulleted lists at the beginning of the line
MD006: true
# MD007/ul-indent - Unordered list indentation
MD007:
# Spaces for indent
indent: 2
# Whether to indent the first level of the list
start_indented: false
# Spaces for first level indent (when start_indented is set)
start_indent: 2
# MD009/no-trailing-spaces - Trailing spaces
MD009:
# Spaces for line break
br_spaces: 2
# Allow spaces for empty lines in list items
list_item_empty_lines: false
# Include unnecessary breaks
strict: false
# MD010/no-hard-tabs - Hard tabs
MD010:
# Include code blocks
code_blocks: true
# Fenced code languages to ignore
ignore_code_languages: []
# Number of spaces for each hard tab
spaces_per_tab: 1
# MD011/no-reversed-links - Reversed link syntax
MD011: true
# MD012/no-multiple-blanks - Multiple consecutive blank lines
MD012:
# Consecutive blank lines
maximum: 1
# Modified for LSR
# GFM does not limit line length
# MD013/line-length - Line length
MD013: false
# # Number of characters
# # line_length: 80
# line_length: 999
# # Number of characters for headings
# heading_line_length: 80
# # Number of characters for code blocks
# code_block_line_length: 80
# # Include code blocks
# code_blocks: true
# # Include tables
# tables: true
# # Include headings
# headings: true
# # Include headings
# headers: true
# # Strict length checking
# strict: false
# # Stern length checking
# stern: false
# MD014/commands-show-output - Dollar signs used before commands without showing output
MD014: true
# MD018/no-missing-space-atx - No space after hash on atx style heading
MD018: true
# MD019/no-multiple-space-atx - Multiple spaces after hash on atx style heading
MD019: true
# MD020/no-missing-space-closed-atx - No space inside hashes on closed atx style heading
MD020: true
# MD021/no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
MD021: true
# MD022/blanks-around-headings/blanks-around-headers - Headings should be surrounded by blank lines
MD022:
# Blank lines above heading
lines_above: 1
# Blank lines below heading
lines_below: 1
# MD023/heading-start-left/header-start-left - Headings must start at the beginning of the line
MD023: true
# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content
MD024: true
# MD025/single-title/single-h1 - Multiple top-level headings in the same document
MD025:
# Heading level
level: 1
# RegExp for matching title in front matter
front_matter_title: "^\\s*title\\s*[:=]"
# MD026/no-trailing-punctuation - Trailing punctuation in heading
MD026:
# Punctuation characters not allowed at end of headings
punctuation: ".,;:!。，；：！"
# MD027/no-multiple-space-blockquote - Multiple spaces after blockquote symbol
MD027: true
# MD028/no-blanks-blockquote - Blank line inside blockquote
MD028: true
# MD029/ol-prefix - Ordered list item prefix
MD029:
# List style
style: "one_or_ordered"
# MD030/list-marker-space - Spaces after list markers
MD030:
# Spaces for single-line unordered list items
ul_single: 1
# Spaces for single-line ordered list items
ol_single: 1
# Spaces for multi-line unordered list items
ul_multi: 1
# Spaces for multi-line ordered list items
ol_multi: 1
# MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines
MD031:
# Include list items
list_items: true
# MD032/blanks-around-lists - Lists should be surrounded by blank lines
MD032: true
# MD033/no-inline-html - Inline HTML
MD033:
# Allowed elements
allowed_elements: []
# MD034/no-bare-urls - Bare URL used
MD034: true
# MD035/hr-style - Horizontal rule style
MD035:
# Horizontal rule style
style: "consistent"
# MD036/no-emphasis-as-heading/no-emphasis-as-header - Emphasis used instead of a heading
MD036:
# Punctuation characters
punctuation: ".,;:!?。，；：！？"
# MD037/no-space-in-emphasis - Spaces inside emphasis markers
MD037: true
# MD038/no-space-in-code - Spaces inside code span elements
MD038: true
# MD039/no-space-in-links - Spaces inside link text
MD039: true
# MD040/fenced-code-language - Fenced code blocks should have a language specified
MD040:
# List of languages
allowed_languages: []
# Require language only
language_only: false
# MD041/first-line-heading/first-line-h1 - First line in a file should be a top-level heading
MD041:
# Heading level
level: 1
# RegExp for matching title in front matter
front_matter_title: "^\\s*title\\s*[:=]"
# MD042/no-empty-links - No empty links
MD042: true
# Modified for LSR
# Disabling, we do not need this
# MD043/required-headings/required-headers - Required heading structure
MD043: false
# # List of headings
# headings: []
# # List of headings
# headers: []
# # Match case of headings
# match_case: false
# MD044/proper-names - Proper names should have the correct capitalization
MD044:
# List of proper names
names: []
# Include code blocks
code_blocks: true
# Include HTML elements
html_elements: true
# MD045/no-alt-text - Images should have alternate text (alt text)
MD045: true
# MD046/code-block-style - Code block style
MD046:
# Block style
style: "consistent"
# MD047/single-trailing-newline - Files should end with a single newline character
MD047: true
# MD048/code-fence-style - Code fence style
MD048:
# Code fence style
style: "consistent"
# MD049/emphasis-style - Emphasis style should be consistent
MD049:
# Emphasis style should be consistent
style: "consistent"
# MD050/strong-style - Strong style should be consistent
MD050:
# Strong style should be consistent
style: "consistent"
# MD051/link-fragments - Link fragments should be valid
MD051: true
# MD052/reference-links-images - Reference links and images should use a label that is defined
MD052: true
# MD053/link-image-reference-definitions - Link and image reference definitions should be needed
MD053:
# Ignored definitions
ignored_definitions:
- "//"

166
.pandoc_template.html5 Normal file
View file

File diff suppressed because one or more lines are too long

99
README.md
View file

@ -1,5 +1,4 @@
OpenSSH Server
==============
# OpenSSH Server
[![Ansible Lint](https://github.com/willshersystems/ansible-sshd/actions/workflows/ansible-lint.yml/badge.svg)](https://github.com/willshersystems/ansible-sshd/actions/workflows/ansible-lint.yml)
[![Ansible Galaxy](http://img.shields.io/badge/galaxy-willshersystems.sshd-660198.svg?style=flat)](https://galaxy.ansible.com/willshersystems/sshd/)
@ -24,8 +23,7 @@ Ubuntu. This is not the default assigned by this module - it will set
via simple password. If you need this functionality, be sure to set
`sshd_PermitRootLogin yes` for those hosts.
Requirements
------------
## Requirements
Tested on:
@ -47,7 +45,6 @@ Tested on:
It will likely work on other flavours and more direct support via suitable
[vars/](vars/) files is welcome.
### Optional requirements
If you want to use advanced functionality of this role that can configure
@ -55,31 +52,33 @@ firewall and selinux for you, which is mostly useful when custom port is used,
the role requires additional collections which are specified in
`meta/collection-requirements.yml`. These are not automatically installed.
You must install them like this:
```
```bash
ansible-galaxy install -vv -r meta/collection-requirements.yml
```
For more information, see `sshd_manage_firewall` and `sshd_manage_selinux`
options below. These roles are supported only on Red Hat based Linux.
Role variables
---------------
## Role variables
### Primary role variables
Unconfigured, this role will provide a `sshd_config` that matches the OS default,
minus the comments and in a different order.
* `sshd_enable`
#### sshd_enable
If set to *false*, the role will be completely disabled. Defaults to *true*.
* `sshd_skip_defaults`
#### sshd_skip_defaults
If set to *true*, don't apply default values. This means that you must have a
complete set of configuration defaults via either the `sshd` dict, or
`sshd_Key` variables. Defaults to *false* unless `sshd_config_namespace` is
set or `sshd_config_file` points to a drop-in directory to avoid recursive include.
* `sshd_manage_service`
#### sshd_manage_service
If set to *false*, the service/daemon won't be **managed** at all, i.e. will not
try to enable on boot or start or reload the service. Defaults to *true*
@ -87,7 +86,7 @@ unless: Running inside a docker container (it is assumed ansible is used during
build phase) or AIX (Ansible `service` module does not currently support `enabled`
for AIX)
* `sshd_allow_reload`
#### sshd_allow_reload
If set to *false*, a reload of sshd wont happen on change. This can help with
troubleshooting. You'll need to manually reload sshd if you want to apply the
@ -95,22 +94,22 @@ changed configuration. Defaults to the same value as `sshd_manage_service`.
(Except on AIX, where `sshd_manage_service` is default *false*, but
`sshd_allow_reload` is default *true*)
* `sshd_install_service`
#### sshd_install_service
If set to *true*, the role will install service files for the ssh service.
Defaults to *false*.
The templates for the service files to be used are pointed to by the variables
- `sshd_service_template_service` (__default__: `templates/sshd.service.j2`)
- `sshd_service_template_at_service` (__default__: `templates/sshd@.service.j2`)
- `sshd_service_template_socket` (__default__: `templates/sshd.socket.j2`)
* `sshd_service_template_service` (**default**: `templates/sshd.service.j2`)
* `sshd_service_template_at_service` (**default**: `templates/sshd@.service.j2`)
* `sshd_service_template_socket` (**default**: `templates/sshd.socket.j2`)
Using these variables, you can use your own custom templates. With the above
default templates, the name of the installed ssh service will be provided by
the `sshd_service` variable.
* `sshd_manage_firewall`
#### sshd_manage_firewall
If set to *true*, the the SSH port(s) will be opened in firewall. Note, this
works only on Red Hat based OS. The default is *false*.
@ -119,7 +118,7 @@ NOTE: `sshd_manage_firewall` is limited to *adding* ports. It cannot be used
for *removing* ports. If you want to remove ports, you will need to use the
firewall system role directly.
* `sshd_manage_selinux`
#### sshd_manage_selinux
If set to *true*, the the selinux will be configured to allow sshd listening
on the given SSH port(s). Note, this works only on Red Hat based OS.
@ -129,7 +128,7 @@ NOTE: `sshd_manage_selinux` is limited to *adding* policy. It cannot be used
for *removing* policy. If you want to remove ports, you will need to use the
selinux system role directly.
* `sshd`
#### sshd
A dict containing configuration. e.g.
@ -140,7 +139,7 @@ sshd:
- 0.0.0.0
```
* `sshd_...`
#### sshd_
Simple variables can be used rather than a dict. Simple values override dict
values. e.g.:
@ -160,44 +159,44 @@ sshd_ListenAddress:
Renders as:
```
```text
ListenAddress 0.0.0.0
ListenAddress ::
```
* `sshd_match`, `sshd_match_1` through `sshd_match_9`
#### sshd_match, sshd_match_1 through sshd_match_9
A list of dicts or just a dict for a Match section. Note, that these variables
do not override match blocks as defined in the `sshd` dict. All of the sources
will be reflected in the resulting configuration file. The use of
`sshd_match_*` variant is deprecated and no longer recommended.
* `sshd_backup`
#### sshd_backup
When set to *false*, the original `sshd_config` file is not backed up. Default
is *true*.
* `sshd_sysconfig`
#### sshd_sysconfig
On RHEL-based systems, sysconfig is used for configuring more details of sshd
service. If set to *true*, this role will manage also the `/etc/sysconfig/sshd`
configuration file based on the following configurations. Default is *false*.
* `sshd_sysconfig_override_crypto_policy`
#### sshd_sysconfig_override_crypto_policy
In RHEL8-based systems, this can be used to override system-wide crypto policy
by setting to *true*. Without this option, changes to ciphers, MACs, public
key algorithms will have no effect on the resulting service in RHEL8. Defaults
to *false*.
* `sshd_sysconfig_use_strong_rng`
#### sshd_sysconfig_use_strong_rng
In RHEL-based systems (before RHEL9), this can be used to force sshd to reseed
openssl random number generator with the given amount of bytes as an argument.
The default is *0*, which disables this functionality. It is not recommended to
turn this on if the system does not have hardware random number generator.
* `sshd_config_file`
#### sshd_config_file
The path where the openssh configuration produced by this role should be saved.
This is useful mostly when generating configuration snippets to Include from
@ -208,7 +207,7 @@ When this path points to a drop-in directory (like
with the variable `sshd_main_config_file`) is checked to contain a proper
`Include` directive.
* `sshd_config_namespace`
#### sshd_config_namespace
By default (*null*), the role defines whole content of the configuration file
including system defaults. You can use this variable to invoke this role from
@ -230,12 +229,12 @@ other match blocks, to ensure they are applied regardless of the previous match
blocks in the existing configuration file. This allows configuring any
non-conflicting options from different roles invocations.
* `sshd_config_owner`, `sshd_config_group`, `sshd_config_mode`
#### sshd_config_owner, sshd_config_group, sshd_config_mode
Use these variables to set the ownership and permissions for the openssh config
file that this role produces.
* `sshd_verify_hostkeys`
#### sshd_verify_hostkeys
By default (*auto*), this list contains all the host keys that are present in
the produced configuration file. If there are none, the OpenSSH default list
@ -247,7 +246,7 @@ able to start on the first attempt.
To disable this check, set this to empty list.
* `sshd_hostkey_owner`, `sshd_hostkey_group`, `sshd_hostkey_mode`
#### sshd_hostkey_owner, sshd_hostkey_group, sshd_hostkey_mode
Use these variables to set the ownership and permissions for the host keys from
the above list.
@ -258,41 +257,39 @@ These variables are used by the role internals and can be used to override the
defaults that correspond to each supported platform. They are not tested and
generally are not needed as the role will determine them from the OS type.
* `sshd_packages`
#### sshd_packages
Use this variable to override the default list of packages to install.
* `sshd_binary`
#### sshd_binary
The path to the openssh executable
* `sshd_service`
#### sshd_service
The name of the openssh service. By default, this variable contains the name of
the ssh service that the target platform uses. But it can also be used to set
the name of the custom ssh service when the `sshd_install_service` variable is
used.
* `sshd_sftp_server`
#### sshd_sftp_server
Default path to the sftp server binary.
### Variables Exported by the Role
* `sshd_has_run`
#### sshd_has_run
This variable is set to *true* after the role was successfully executed.
Dependencies
------------
## Dependencies
None
For tests the `ansible.posix` collection is required for the `mount` role to
For tests, the `ansible.posix` collection is required for the `mount` role to
emulate FIPS mode.
Example Playbook
----------------
## Example Playbook
**DANGER!** This example is to show the range of configuration this role
provides. Running it will likely break your SSH access to the server!
@ -321,7 +318,7 @@ provides. Running it will likely break your SSH access to the server!
Results in:
```
```text
# Ansible managed: ...
Compression yes
GSSAPIAuthentication no
@ -362,7 +359,8 @@ for example:
You can just add a configuration snippet with the `sshd_config_namespace`
option:
```
```yaml
---
- hosts: all
tasks:
@ -378,20 +376,20 @@ option:
LS_COLORS
EDITOR
```
The following snippet will be added to the default configuration file
(if not yet present):
```
```text
# BEGIN sshd system role managed block: namespace accept-env
Match all
AcceptEnv LANG LS_COLORS EDITOR
# END sshd system role managed block: namespace accept-env
```
More example playbooks can be found in [`examples/`](examples/) directory.
Template Generation
-------------------
## Template Generation
The [`sshd_config.j2`](templates/sshd_config.j2) and
[`sshd_config_snippet.j2`](templates/sshd_config_snippet.j2) templates are
@ -401,14 +399,11 @@ to the `options_body` and/or `options_match`.
To regenerate the templates, from within the `meta/` directory run:
`./make_option_lists`
License
-------
## License
LGPLv3
Authors
-------
## Authors
Matt Willsher <matt@willsher.systems>