Setting up an SSL certificate

This article guides you through setting up an SSL certificate on your Q.wiki server. Depending on your Q.wiki version, follow the relevant sections:

• New installation: Follow the sections "Create a Certificate Signing Request" and "Set up SSL Certificate"
• Renew certificate (Version < 6.8): See section "Set up SSL Certificate"
• Renew certificate (Version ≥ 6.8): See section "Update SSL Certificate from Version 6.8"

Create a Certificate Signing Request (CSR)

To set up SSL, you need to create a CSR and a private key. Follow these steps:

1. Generate a private key

Navigate to the SSL directory and create a new key:

cd /etc/ssl/private
openssl genrsa -out fqdn.key.pem 2048

Replace fqdn with the fully qualified domain name of your Q.wiki server (e.g., qwiki.acme.local).

2. Create a CSR configuration file

Create a configuration file for the CSR:

vim fqdn.csr.conf

Insert the following configuration and replace the highlighted values with your information:

[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
prompt = no

[req_distinguished_name]
C = DE
ST = NRW
L = AACHEN
O = Your Organization
OU = IT-Services
CN = qwiki.acme.local
emailAddress = admin@example.de

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = qwiki.acme.local
DNS.2 = qwikiserver.acme.local

CN: The URL used to access Q.wiki in your browser
DNS.1: The public DNS name
DNS.2: The server's FQDN

3. Generate the CSR from the configuration

Save the configuration file and create the CSR:

openssl req -new -out fqdn.csr -key fqdn.key.pem -config fqdn.csr.conf

The file fqdn.csr is created in the current directory. You can now download it to your local computer via SCP or copy the contents and paste it into a local file. Use this CSR to request an SSL certificate from your certificate authority (CA).

Set up SSL Certificate

Once you have received the certificate from your CA, follow these steps:

1. Copy certificate and key to the server

Copy the certificate and private key to the Q.wiki server in the directory /etc/ssl/private. All subsequent commands are executed in this directory.

2. Check file format

Q.wiki requires an RSA key (without password) and an X.509 certificate in Base64 format. If your certificate is in DER or PKCS#12 format, it must be converted.

Convert DER format

openssl x509 -inform der -in fqdn.xyz -out fqdn.cert.pem

Convert PKCS#12 format

Extract private key:

openssl pkcs12 -in fqdn.pfx -nocerts -nodes -out fqdn.key.pem

Extract certificate:

openssl pkcs12 -in fqdn.pfx -clcerts -nokeys -out fqdn.cert.pem

3. Verify private key

Test whether the key is correctly formatted:

openssl rsa -noout -in fqdn.key.pem

If a password prompt appears, the password must be removed – otherwise manual password entry will be required on every web server restart.

4. Set file permissions

chown root:root fqdn.*
chmod 0600 fqdn.*

5. Edit Nginx configuration (first-time setup only)

Open the Nginx configuration file:

vim /etc/nginx/sites-enabled/qwiki_http.conf

Replace the entire contents with the following configuration (adjust the highlighted values):

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name qwiki_http;

    rewrite ^/(.*)$ https://qwiki.acme.local/$1 permanent;
}

server {
    listen 443 default_server ssl;
    listen [::]:443 default_server ssl;

    server_name qwiki_https;

    root /var/www/qwikis/core;

    ssl_certificate /etc/ssl/private/fqdn.cert.pem;
    ssl_certificate_key /etc/ssl/private/fqdn.key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location ~ (/pub/System|/robots.txt) {
        sendfile on;
        tcp_nopush on;
        expires 7d;
        add_header Cache-Control "public, no-transform";
    }

    location /api/phoenix {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://elixir;
    }

    location / {
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://qwiki;
    }
}

6. Update Q.wiki configuration (first-time setup only)

Open the Q.wiki configuration file:

vim /var/www/qwiki/core/lib/LocalSite.cfg

Find the DefaultUrlHost entry and change the protocol from http to https:

$Foswiki::cfg{DefaultUrlHost} = 'https://qwiki.acme.local';

Save the file.

7. Restart services

a2enmod ssl
systemctl restart nginx qwiki

The SSL certificate is now active. Verify the connection by accessing Q.wiki via https://.

Update SSL Certificate from Version 6.8

In Q.wiki version 6.8 and later, certificates can be managed through the user interface. Follow these steps:

1. Open Q.wiki Commander Shell

qmmander

2. Open Q.wiki configuration

Navigate in the menu to the security settings and open the certificate management.

3. Update certificate and key

Update the paths to the new certificate and key. These are typically stored in /root/qwiki/:

ABSOLUTE_TLS_CRT_PATH: /root/qwiki/fqdn.cert.pem
ABSOLUTE_TLS_KEY_PATH: /root/qwiki/fqdn.key.pem

4. Save configuration and reload

Save the changes and run the following option in the Q.wiki Commander:

Update certificate

The new certificates are activated immediately without requiring a restart.