Skip to content

Workstation setup for a new employee

This chapter describes the steps for a new employee to setup a workstation for working with the playbook-infrastructure and Ansible Cake.

Supported workstation operating systems

Ubuntu Linux and Debian Linux are supported.

Mac OSX is kind of supported. It might require some debugging.

Windows is kind of supported via WSDL2. It might require some debugging.

Ubuntu VMs running on your workstation are supported, but might be cumbersome unless you run a graphical system in it.

Generating a SSH keypair

SSH is used to connect to servers. It is used as the communication channel by Ansible and other tools. To use it, you need a SSH private and public key.

Your SSH public key will be stored in the playbook-infrastructure-company so it can be installed on the servers. After generating it, please open a issue in your companies Gitlab in the playbook-infrastructure-company git repository and post your public key.

Run the following commands to generate the SSH keypair on your workstation:

# Install the pwgen utility to generate reasonably secure passwords
user@workstation:~$ sudo apt install pwgen

# Generate a reasonably secure password.
# Make sure to save the password to your _private_ password store! (not the playbook one)
user@workstation:~$ pwgen --secure --symbols "$(($RANDOM%20+40))" 1

# Generate a SSH keypair (provide the password above when the command asks for it)
user@workstation:~$ ssh-keygen -t ed25519 -o -a 100

# If this gives an error "unable to establish connection to ssh-agent" or similar, execute:
user@workstation:~$ eval ssh-agent -s

# Provide the output in a Gitlab issue in your companies playbook-infrastructure-company git repository
user@workstation:~$ cat ~/.ssh/id_ed25519.pub
<paste the output into a Gitlab issue>

To use your ssh private key on your workstation without having to enter the password every single time you use the ssh command, use the following command. It will ask you for the password and then cache it for your current session:

user@workstation:~$ ssh-add ~/.ssh/id_ed25519

To view loaded ssh private keys run:

user@workstation:~$ ssh-add -l

SSH u.name@

All employees should SSH login with their username, which is usually in the format (example for John Doe) "j.doe" (or "jdoe" where dots are not allowed in usernames), and then use sudo:

ssh j.doe@exa-util-prod-deploy-1
sudo systemctl restart apache2.service

Login directly as root@ is possible for "admin" users (commonly defined in ssh_users_admins) discouraged.

cake ssh will by default also use your username, which is defined in .env.user:

CAKE master * grep ssh_ .env.user
export cake_ssh_username="j.doe"

CAKE master * cake ssh deploy
cake INFO Executing: ssh j.doe@172.16.16.12

Generating a GnuPG keypair

GnuPG (also called GPG) is used to encrypt files in order for them to only be accessible to a specific group of people. This is used to share secrets like passwords between employees using Blunix Stack.

To generate a GPG keypair, run the following commands. Please read the commands first and replace Your Name with your real name and so on.

# Generate a secure passphrase
user@workstation:~$ pwgen --secure --symbols "$(($RANDOM%20+40))" 1

# Create a temporary config file for the keypair generation
user@workstation:~$ gpg2 --expert --full-gen-key

Please select what kind of key you want:
   (1) RSA and RSA (default)
   [...]
   (9) ECC and ECC
   [...]
Your selection? 9

Please select which elliptic curve you want:
   (1) Curve 25519
   [...]
Your selection? 1

Please specify how long the key should be valid.
         0 = key does not expire
           = key expires in 5 days
         w = key expires in n weeks
         m = key expires in n months
         y = key expires in n years
Key is valid for? (0)

Key does not expire at all
Is this correct? (y/N) y

Real name: User Name
Email address: u.name@example.com
Comment: CTO Example GmbH

You selected this USER-ID:
    "User Name (CTO Example GmbH) <u.name@example.com>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

Then enter the passphrase.

To view which GPG keys the gpg-agent has loaded, run the following command:

gpg-connect-agent 'keyinfo --list' /bye

To view your gpg keys, use:

gpg2 --list-keys

To load your GPG private key with the gpg-agent, simply decrypt any file encrypted for you.

Important GPG notes!

  • GPG supports a public (as in the whole internet) key sharing infrastructure where a users gpg public key can be made accessible to the internet and "trusted" by others (GPG web of trust). This is considered a failed project and should not be used!
  • Do not use the GPG keypair generated for Blunix Stack for encrypting Emails. Please generate a second keypair for that.

Installing the wireguard VPN

Wireguard is used as the VPN tool to access the private internal network and DNS of your companies infrastructure.

Wireguard is available for a multitude of operating systems and can be downloaded here: https://www.wireguard.com/install/.

You can use it on your workstation as well as your smartphone, tablet and most other common devices running Android, IOS, Mac OSX, Windows or several Linux derivatives. Installing wireguard on your smartphone and mobile devices gives you on-the-go access to tools like the monitoring system, staging environments or similar.

Setup for Ubuntu and Debian Linux

sudo apt install wireguard

cd /etc/wireguard
umask 077
wg genkey | tee company.key | wg pubkey > company.pub
# wireguard public key output will be printed here

Provide the wireguard public key output to Blunix using a gitlab issue in your playbook-infrastructure-company gitlab repository. Wait for your Blunix consultant to notify you and execute this command to download your wireguard config file:

scp root@gateway-1:/etc/wireguard/cusadm/clients/u.name@example.com.conf /etc/wireguard/example.conf

Setup for Mac OSX

brew install wireguard-tools

mkdir -p /usr/local/etc/wireguard
cd /usr/local/etc/wireguard
umask 077

wg genkey | tee company.key | wg pubkey > company.pub
# wireguard public key output will be printed here

scp root@gateway-1:/etc/wireguard/cusadm/clients/u.name@example.com.conf /etc/wireguard/example.conf

Configuration

Copy and paste your wireguard public key into an issue in your companies Gitlab repository for the playbook-infrastructure-company, so that your admin or a Blunix GmbH consultant can add your public key to the wireguard servers.

If you do not have scp access to the gateway servers, the admin or Blunix GmbH consultant will provide you with a config file in that issue.

Graphical wireguard clients

For graphical clients, you will be provided with the following information:

  • The wireguard servers public key
  • The wireguard servers public IP address and port
  • The wireguard servers internal IPs for DNS
  • The wireguard servers "Allowed IPs" setting, describing the subnets reachable via the VPN
  • Your wireguard clients private IP address

Starting the wireguard VPN

To start the wireguard service on the command line, run the following command:

systemctl start wg-quick@company.service

Where "company" is the filename of /etc/wireguard/company.conf.

To show the status information for the VPN connection:

sudo wg show

Permanently enabling wireguard

To start wireguard on boot, run:

sudo systemctl enable wg-quick@company.service
sudo systemctl start wg-quick@company.service
sudo wg show

Mac OSX DNS

The DNS setting in the wireguard config is ignored by OSX. Because of this, the DNS server has to be manually configured in the system settings as primary DNS server.
The DNS server IP has to be the same as in the wireguard config. You can comment out the DNS setting in the wireguard config.

Installing Docker

The ansible-cake tool runs in a Docker container. You only need to install Docker on your workstation, docker-compose and alike are not required.

Please follow the installation instructions at docs.docker.com to install Docker.

Cloning the playbook-infrastructure-company repository

It is recommended that you create a ~/code/ directory in your home directory to organize all code, not just the one from Blunix Stack or your company, but all source code you work on during the lifetime of your workstation.

# Install git
user@workstation:~$ sudo apt install git

# Create the code directory
user@workstation:~$ mkdir -p code/git/git.cus.int/
user@workstation:~$ cd code/git/git.cus.int/

# Clone the playbook-infrastructure-company git repository
# You might have to type "yes" here to accept your companies Gitlab servers SSH public key
# (git runs via SSH in most cases)
user@workstation:~/code/git/git.cus.int$ git clone git@git.cus.int/ansible/playbook-infrastructure-company.git
user@workstation:~/code/git/git.cus.int$ cd playbook-infrastructure-company

Starting the ansible-cake Docker container

To start the ansible-cake Docker container, simply run the following script:

user@workstation:~/code/git/git.cus.int/playbook-infrastructure-company$ ./start-cake.sh