Everbrent/cis
9
0
Fork 0
mirror of https://github.com/m8tin/cis.git synced 2025-12-06 15:58:26 +01:00
Code Issues Packages Projects Releases Wiki Activity

README updated

Browse Source
This commit is contained in:
Martin Berghaus
2025-03-02 00:12:33 +01:00
parent 91816bedf8
commit e782848efd
1 changed files with 88 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
README.md
View File

@@ -1,35 +1,109 @@
Core Infrastructure System (CIS) Core Infrastructure System (CIS)
================================ ================================
Setup a new host The main idea is to use git to keep scripts, definitions and state in sync across all hosts.
---------------- Currently an operating instance uses one repository for this core functionality and scripts,
another to distibute the definitions and a third one to share the state.
### Preconditions If a script or a definition has to be changed an independent working copy is needed to push the adaptions.
To deploy the system you have to clone this repository to the host as root user. States can be changed by a host itself. Then we need a mechanism that informs all hosts to execute a `git pull`.
Therefore you have to register the SSH public key of that root user as deploy key to allow readonly access to this repository.
We use the modern ed25519 keys, so the public key of root is stored at this location: We use a Git server as syncronisation point and use a web hook to send the notification.
Because the should not be an agent to be installed on each host, we use jenkins to execute an update script via ssh.
This allows us to use standard software without having to program something that may contain a security problem.
Setup the first or a new host
-----------------------------
1. Update the host and ensure git is installed
2. Set the long hostname (fqdn)
3. Create ssh keys for user root (ssh key type ed25519)
You can use this script to do so: [prepareThisHostBeforeCloning.sh](./prepareThisHostBeforeCloning.sh)
### Ensure the existence of the repositories for your definitions and the state
This should be necessary just if you set up the first host.
You can use the following scripts to assist the process:
- [prepareDefinitionsRepository.sh](./prepareDefinitionsRepository.sh)
- [prepareStatesRepository.sh](./prepareStatesRepository.sh)
### Register the public ssh key of user root
This is an example for `example.net` as domain of the host.
1. __Scripts:__
The public ssh key of the root user must be registered as a deploy key for the this repository,
which grants __readonly access__.
A root user of a host should only be able to update the local cloned repository (`cis`) to a new version via `git pull`.
2. __Definitions:__
The public ssh key of the root user must be registered as a deploy key for the definitions repository,
which grants __readonly access__.
User root should only be able to update the local cloned repository (`cis-definition-example.net`) to a new version via `git pull`.
3. __States:__
The public ssh key of the root user must be registered as a deploy key for the states repository,
which grants __write access__.
User root should be able to push new state to the cloned repository (`cis-state-example.net`) via `git push`.
### Clone the Infrastructure System (cis) repository and complete the setup
After you registered the printed root's public key of this host you can clone the repository and execute the setup script:
```sh
# Note the tailing '/cis', because we want to clone the repository to that folder
git clone ssh://git@git.example.dev:22448/cis.git /cis
# Execute the setup script
/cis/setupCoreOntoThisHost.sh
```
<br>
<br>
<br>
Setup a new host step by step manually
--------------------------------------
To deploy cis you have to clone this repository to the host as root user.
Therefore you have to set the correct long hostname (fqdn) create a pair of ssh keys (key type ed25519) for user root
and register the SSH public key of root as __deploy key__ to allow readonly access to this repository:
1. First become root: 1. First become root:
```sh ```sh
sudo -i sudo -i
``` ```
2. Set the long hostname: 2. Update Ubuntu:
```sh
hostnamectl set-hostname "the-new-unique-long-hostname (fqdn, eg.: host1.example.net)"
```
3. Update Ubuntu:
```sh ```sh
# DO NOT SKIP THIS STEP # DO NOT SKIP THIS STEP
apt update; apt upgrade -y apt update; apt upgrade -y
``` ```
4. Install git if needed: 3. Install git if needed:
```sh ```sh
git --version > /dev/null || apt install git git --version > /dev/null || apt install git
``` ```
4. Set the long hostname:
```sh
hostnamectl set-hostname "the-new-unique-long-hostname (fqdn, eg.: host1.example.net)"
```
5. If not exist generate the ssh key pair and print the public key of the user root: 5. If not exist generate the ssh key pair and print the public key of the user root:
```sh ```sh
# -t type of the key pair # -t type of the key pair
@@ -45,33 +119,10 @@ We use the modern ed25519 keys, so the public key of root is stored at this loca
&& cat "/root/.ssh/id_ed25519.pub") && cat "/root/.ssh/id_ed25519.pub")
``` ```
This key has to be registerd via gitea web ui as deploy key into the repositories as documented in chapter "Register public host key". This key has to be registerd via gitea web ui as deploy key into this repository.
### Register public host key
This is an example for `example.net` as domain of the host owner.
1. Repository `cis`, allow __readonly__ access only.
2. Repository `cis-definition-example.net`, allow __readonly__ access only.
3. Repository `cis-state-example.net`, allow __writable__ access.
### Clone the Infrastructure System (cis) repository
After you registered the printed root's public key of this host you can clone the repository and execute the setup script:
```sh
# Note the tailing '/cis', because we want to clone the repository to that folder
git clone ssh://git@git.example.dev:22448/cis.git /cis
# Execute the setup script
/cis/setupCoreOntoThisHost.sh
```
<br>
<br>
<br>
How it works How it works
------------ ------------
We add a webhook to each gitea repository that belongs to CIS: We add a webhook to each gitea repository that belongs to CIS: