Catching up docs-2.x

.github/workflows/ce-provision-publish-docs.yml

@@ -8,16 +8,29 @@ on:
       - 1.x
       - 2.x
   workflow_dispatch:
+# Set target docs branch name
+env:
+  docs_branch: docs-${{ github.event.pull_request.base.ref }}
 
 jobs:
-  # Set the job key. The key is displayed as the job name
-  # when a job name is not provided
-  public-docs:
-    # Only run the job if it is not coming from a documentation branch
-    if: ${{ github.event.pull_request.head.ref != 'docs-${{ github.event.pull_request.base.ref }}' }}
-    # Name the Job
+  # See https://stackoverflow.com/a/74378072
+  set-docs-branch:
+    name: Make docs branch name available to publish-docs job
+    runs-on: ubuntu-latest
+    outputs:
+      docs_branch: ${{ steps.init.outputs.docs_branch }}
+
+    steps:
+      - name: Make environment variables global
+        id: init
+        run: |
+          echo "docs_branch=${{ env.docs_branch }}" >> $GITHUB_OUTPUT
+
+  publish-docs:
     name: Publish the ce-provision docs to GitHub
-    # Set the type of machine to run on
+    # Only run the job if it is not coming from a documentation branch
+    needs: set-docs-branch
+    if: ${{ github.event.pull_request.head.ref != needs.set-docs-branch.outputs.docs_branch }}
     runs-on: ubuntu-latest
 
     # Use our ce-dev Debian base container
@@ -45,14 +58,18 @@ jobs:
       # First build and publish the markdown docs
       - name: Build and commit table of contents and README files back to the repo
         run: |
+          /usr/bin/git fetch origin 2.x
+          /usr/bin/git merge origin/${{ github.event.pull_request.base.ref }} --allow-unrelated-histories
           /bin/sh contribute/toc.sh
           /usr/bin/find . -name "*.md" | xargs git add
-          /usr/bin/git diff --quiet && git diff --staged --quiet || git commit -am "GitHub Actions - updating markdown docs - ${{ steps.date.outputs.date }}"
-          /usr/bin/git push
+          /usr/bin/git diff --staged --quiet || /usr/bin/git commit -am "GitHub Actions - updating markdown docs - ${{ github.event.repository.updated_at }}"
+          /usr/bin/git push origin docs-${{ github.event.pull_request.base.ref }}
 
       # Create docs pull request
-      - name: Create a documentation pull request
-        run: gh pr create --base ${{ github.event.pull_request.base.ref }} --head docs-${{ github.event.pull_request.base.ref }} --title "Documentation update" --body "**Automated pull request** created by GitHub Actions because of a documentation update."
+      - name: Create documentation pull requests
+        run: |
+          gh pr create --base ${{ github.event.pull_request.base.ref }} --head docs-${{ github.event.pull_request.base.ref }} --title "Documentation update - ${{ github.event.pull_request.base.ref }}" --body "**Automated pull request** created by GitHub Actions because of a documentation update." || echo "No commits between ${{ github.event.pull_request.base.ref }} and docs-${{ github.event.pull_request.base.ref }} - no PR created!"
+          gh pr create --base devel-${{ github.event.pull_request.base.ref }} --head docs-${{ github.event.pull_request.base.ref }} --title "Documentation update - devel-${{ github.event.pull_request.base.ref }}" --body "**Automated pull request** created by GitHub Actions because of a documentation update." || echo "No commits between devel-${{ github.event.pull_request.base.ref }} and docs-${{ github.event.pull_request.base.ref }} - no PR created!"
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

docs/roles/_init.md

@@ -22,6 +22,13 @@ _ce_ansible_timer_name: upgrade_ansible
 # Generally it is recommended to place these in your ce-provision-config repository under hosts/group_vars/all
 #_aws_profile: example # boto profile name
 #_aws_region: eu-west-1
+_aws_vpc_cidr_base: 10.0
+
+# AWS tags
+_aws_resource_name: "" # Name
+# _profile: web_server # Profile
+# _env_type: dev # Env
+# _infra_name: acme # Infra
 
 _init:
   # A list of var directories to include. We only support .yml extensions.

docs/roles/aws/aws_ami.md

@@ -29,7 +29,7 @@ aws_ami:
   ami_name: "example"
   owner: "136693071363" # Global AWS account ID of owner, defaults to Debian official
   ssh_username: "admin"
-  public_key_name: id_ecdsa.pub # from Debian 12 (Bookworm) onwards RSA keys, i.e. id_rsa.pub, are deprecated
+  public_key_name: id_ed25519.pub # from Debian 12 (Bookworm) onwards RSA keys, i.e. id_rsa.pub, are deprecated
   encrypt_boot: false
   # EBS volume options
   device_name: /dev/xvda # default for Debian AMIs

docs/roles/aws/aws_vpc.md

@@ -10,23 +10,132 @@ aws_vpc:
   aws_profile: "{{ _aws_profile }}"
   region: "{{ _aws_region }}"
   name: example-vpc-2
-  cidr_block: "10.0.0.0/16"
+  cidr_block: "{{ _aws_vpc_cidr_base }}.0.0/16"
   # ipv6_cidr: true # uncomment to request an Amazon-provided IPv6 CIDR block with /56 prefix length.
   tags: {}
     #Type: "util"
   state: present
   assign_instances_ipv6: false
-  security_groups:
-    []
-    # - name: web - open
-    #   description: Allow all incoming traffic on ports 80 and 443
-    #   rules:
-    #     - proto: tcp
-    #       ports:
-    #         - 80
-    #         - 443
-    #       cidr_ip: 0.0.0.0/0
-    #       rule_desc: Allow all incoming traffic on ports 80 and 443
+  # List of security groups to create in this VPC, see below for example structure.
+  security_groups: "{{ _security_groups_defaults }}"
+
+# Load common security groups below into a list to use with the aws_vpc.security_groups variable.
+_security_groups_defaults:
+  - "{{ _common_security_groups.common_network }}"
+  - "{{ _common_security_groups.ssh_open }}"
+  - "{{ _common_security_groups.web_open }}"
+  - "{{ _common_security_groups.mailpit_open }}"
+  - "{{ _common_security_groups.ftp_open }}"
+  - "{{ _common_security_groups.sftp_open }}"
+  - "{{ _common_security_groups.ossec }}"
+  - "{{ _common_security_groups.openvpn }}"
+
+# Here is a set of example and commonly required security groups.
+# This closely follows our common firewall rules in roles/debian/firewall_config.
+_common_security_groups:
+  common_network:
+    name: common_network
+    description: Common network access configuration for all servers.
+    rules:
+      - proto: icmp
+        from_port: 8 # ICMP type (8 is IPv4 echo)
+        to_port: -1 # ICMP subtype (-1 for any)
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow ICMP IPv4 ping.
+      - proto: icmp
+        from_port: 128 # ICMP type (128 is IPv6 echo)
+        to_port: -1 # ICMP subtype (-1 for any)
+        cidr_ipv6: "::/0"
+        rule_desc: Allow ICMP IPv6 ping.
+      - proto: tcp
+        cidr_ip: "{{ _aws_vpc_cidr_base }}.0.0/16" # see _init - 10.0.0.0/16 by default
+        ports:
+          - 0-65535
+        rule_desc: Allow all tcp traffic on internal network.
+      - proto: udp
+        cidr_ip: "{{ _aws_vpc_cidr_base }}.0.0/16"
+        ports:
+          - 0-65535
+        rule_desc: Allow all udp traffic on internal network.
+    rules_egress:
+      - proto: tcp
+        cidr_ip: 0.0.0.0/0
+        ports:
+          - 1-1024
+          - 2049
+        rule_desc: Allow ports 1-1024 and 2049 for NFS over tcp as standard.
+      - proto: udp
+        cidr_ip: 0.0.0.0/0
+        ports:
+          - 1-1024
+        rule_desc: Allow ports 1-1024 over udp as standard.
+  ssh_open:
+    name: ssh_open
+    description: Allow all incoming traffic on port 22.
+    rules:
+      - proto: tcp
+        ports:
+          - 22
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow all incoming tcp traffic on port 22.
+  web_open:
+    name: web_open
+    description: Allow all incoming web traffic on ports 80 and 443.
+    rules:
+      - proto: tcp
+        ports:
+          - 80
+          - 443
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow all incoming tcp traffic on ports 80 and 443.
+  mailpit_open:
+    name: mailpit_open
+    description: Allow all incoming traffic on port 8025 for Mailpit.
+    rules:
+      - proto: tcp
+        ports:
+          - 8025
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow all incoming tcp traffic on port 8025.
+  ftp_open:
+    name: ftp_open
+    description: Allow all incoming traffic on ports 20 and 21 for FTP.
+    rules:
+      - proto: tcp
+        ports:
+          - 20
+          - 21
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow all incoming tcp traffic on ports 20 and 21.
+  sftp_open:
+    name: sftp_open
+    description: Allow all incoming traffic on ports 989 and 990 for sFTP.
+    rules:
+      - proto: tcp
+        ports:
+          - 898
+          - 990
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow all incoming tcp traffic on ports 989 and 990.
+  ossec:
+    name: ossec
+    description: Allow all incoming traffic on ports 1514 and 1515 for OSSEC.
+    rules:
+      - proto: udp
+        ports:
+          - 1514
+          - 1515
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow all incoming udp traffic on ports 1514 and 1515.
+  openvpn:
+    name: openvpn
+    description: Allow all incoming traffic on port 1194 for OpenVPN.
+    rules:
+      - proto: udp
+        ports:
+          - 1194
+        cidr_ip: 0.0.0.0/0
+        rule_desc: Allow all incoming udp traffic on port 1194.
 
 ```
 

docs/roles/debian/ce_deploy.md

@@ -20,9 +20,9 @@ ce_deploy:
   # Other ce-deploy settings.
   aws_support: true # installs boto3
   new_user: true # set to false if user already exists or is ephemeral, e.g. an LDAP user
-  ssh_key_bits: "521" # recommended to use 4096 for RSA keys, 521 is the maximum for ECDSA keys
-  ssh_key_type: ecdsa # set to rsa to create an RSA key
-  public_key_name: id_ecdsa.pub # this might be id_rsa.pub for RSA keys, existing users may have a key of a different name
+  ssh_key_bits: "521" # ignored for ED25519 keys, recommended to use 4096 for RSA keys, 521 is the maximum for ECDSA keys
+  ssh_key_type: ed25519 # set to rsa to create an RSA key or ecdsa to create an ECDSA key
+  public_key_name: id_ed25519.pub # this might be id_rsa.pub for RSA keys or id_ecdsa.pub for ECDSA keys, existing users may have a key of a different name
   username: "{{ _ce_deploy.username }}"
   own_repository: "https://github.com/codeenigma/ce-deploy.git"
   own_repository_branch: "master"

docs/roles/debian/ce_provision.md

@@ -21,9 +21,9 @@ ce_provision:
   new_user: "{{ _init.ce_provision_new_user }}" # see _init defaults, set to false if user already exists or is ephemeral, e.g. an LDAP user
   username: "{{ _ce_provision_username }}" # see _init defaults
   #uid: "{{ _init.ce_provision_uid }}" # see _init defaults, optionally hardcode the UID for this user
-  ssh_key_bits: "521" # recommended to use 4096 for RSA keys, 521 is the maximum for ECDSA keys
-  ssh_key_type: ecdsa # set to rsa to create an RSA key
-  public_key_name: id_ecdsa.pub # this might be id_rsa.pub for RSA keys, existing users may have a key of a different name
+  ssh_key_bits: "521" # ignored for ED25519 keys, recommended to use 4096 for RSA keys, 521 is the maximum for ECDSA keys
+  ssh_key_type: ed25519 # set to rsa to create an RSA key or ecdsa to create an ECDSA key
+  public_key_name: id_ed25519.pub # this might be id_rsa.pub for RSA keys or id_ecdsa.pub for ECDSA keys, existing users may have a key of a different name
   # Main repo.
   own_repository: "https://github.com/codeenigma/ce-provision.git"
   own_repository_branch: "master"

docs/roles/debian/firewall_config.md

@@ -61,6 +61,7 @@ firewall_config:
   rulesets:
     - ssh_open
     - web_open
+    - common_network # rule always needs to be last so the DROP rules in the OUTPUT chain get applied at the end
 
   # Ruleset definitions
   # Permitted rule lists
@@ -91,6 +92,29 @@ firewall_config:
   letsencrypt:
     firewall_allowed_tcp_ports:
       - "80"
+  # Standard ports for Prometheus outbound rules to allow scraping of exporters
+  prometheus_server_scraping:
+    firewall_additional_rules:
+      - "iptables -A OUTPUT -p tcp --dport 9100 -j ACCEPT" # allow scraping node exporter
+      - "iptables -A OUTPUT -p tcp --dport 9101 -j ACCEPT" # allow scraping process exporter
+      - "iptables -A OUTPUT -p tcp --dport 9093 -j ACCEPT" # allow posting to alertmanager
+      - "iptables -A OUTPUT -p tcp --dport 9115 -j ACCEPT" # allow scraping blackbox exporter
+  # Commonly required outbound ports for PHP web servers
+  common_web:
+    firewall_additional_rules:
+      - "iptables -A OUTPUT -p tcp --dport 2049 -j ACCEPT" # allow NFS
+      - "iptables -A OUTPUT -p udp --dport 2049 -j ACCEPT" # allow NFS
+      - "iptables -A OUTPUT -p tcp --dport 3306 -j ACCEPT" # allow MySQL
+  # Recommended general firewall settings
+  common_network:
+    firewall_additional_rules:
+      - "iptables -A INPUT -p icmp --icmp-type 8 -s 0/0 -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT" # ICMP ping in
+      - "iptables -A INPUT -p icmp --icmp-type 128 -s 0/0 -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT" # ICMP ping in
+      - "iptables -A OUTPUT -p icmp --icmp-type 0 -d 0/0 -m state --state ESTABLISHED,RELATED -j ACCEPT" # ICMP ping out
+      - "iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT" # established connections out
+      - "iptables -A OUTPUT -o lo -j ACCEPT" # allow all local traffic
+      - "iptables -A OUTPUT -p tcp --dport 1025:65535 -j DROP" # block high port tcp traffic outbound
+      - "iptables -A OUTPUT -p udp --dport 1025:65535 -j DROP" # block high port udp traffic outbound
   ossec:
     firewall_allowed_udp_ports:
       - "1514"