Configuration

LinkAhead is configured via so-called profiles. A profile is a directory that contains at least a profile.yml file. Via this file the most important configuration options can be set.

The profile that is used when LinkAhead starts is configured in the file /etc/linkahead/linkahead.conf. After a fresh installation, this is the path to the default profile (E.g. /usr/share/linkahead/profiles/default/profile.yml).

You should copy the default profile to get a starting point:

cp -r /usr/share/linkahead/profiles/default ~/.config/linkahead

These paths are examples but may depend on your system and your preferences.

Afterwards, set the path in the configuration file /etc/linkahead/linkahead.conf to your new profile

SSL Encryption

In order to use HTTPS (which is strongly recommended) you need to provide a certificate that is used by the server.

Creating the Java Key Store

The LinkAhead server expects a Java Key Store named caosdb.jks. In the following we will distinguish two cases:

  1. You have a valid certificate that you want to provide.
  2. You want to create and use a self-signed certificate.

Note, that the first option is strongly recommended (ask you IT-department, if you do not know how to get a valid certificate).

Option 1: Using an existing certificate

Suppose you have a certificate and private key file named fullchain.pem and privkey.pem, respectively, you can create a key store from those files.

Note that the full certificate chain should be included into the fullchain.pem, not only the server certificate itself.

During the execution of the following two commands you will be asked to supply a password with at least six characters. Use the same password for both commands and note that you will need it in a later step again.

openssl pkcs12 -export -inkey privkey.pem -in fullchain.pem -out all-certs.pkcs12
keytool -importkeystore -srckeystore all-certs.pkcs12 -srcstoretype PKCS12  -deststoretype pkcs12 -destkeystore caosdb.jks

keytool is provided by openjdk-14-jre-headless, for example.

Option 2: Creating a self-signed certificate.

In order to create a self-signed certificates (not recommended for production use) you can do (You can replace localhost by your host name):

mkdir certificates; cd certificates
keytool -genkey -keyalg RSA -alias selfsigned -keystore caosdb.jks -validity 375 -keysize 2048 -ext san=dns:localhost
keytool -importkeystore -srckeystore caosdb.jks -destkeystore caosdb.p12 -deststoretype PKCS12 -srcalias selfsigned
openssl pkcs12 -in caosdb.p12 -nokeys -out caosdb.cert.pem

During the execution of the following two commands you will be asked to supply a password with at least six characters. Use the same password for both commands and note that you will need it in a later step again.

The last command exports only the public part of the certificate. The resulting cert.pem can safely be given to users to allow SSL verification.

Using the Java Key Store

Place the resulting file caosdb.jks in the profile directory under the path custom/other/cert/caosdb.jks. All certificate files should be readable/accessible only by the user that runs the LinkAhead server.

The password to the certificate needs to be supplied to the LinkAhead server via a configuration file. For example, create a file custom/caosdb-server/conf/ext/server.conf.d/90-keystore.conf with the content

CERTIFICATES_KEY_PASSWORD=<password>
CERTIFICATES_KEY_STORE_PASSWORD=<password>

where you replace <password> with the password that you used when creating the key store.

Now, you can restart LinkAhead: sudo systemctl restart linkahead. If you used Option 1 above with a certificate that is signed by a known Certificate Authority, you can now access LinkAhead with a browser (Unless you changed the port: https://domain:10443) and SSL will work fine.

If you used a self-signed certificate, the browser will warn you that The certificate is not trusted because it is self-signed..

In order to allow the Python client to use SSL encryption with a self-signed certificate, you need to supply the public part, that you created above: caosdb.cert.pem. Provide the path to that file in the configuration file of the client pycasodb.ini: cacert=/path/to/caosdb.cert.pem

Troubleshooting

Check what certificate is delivered by the server

In order to exclude the possibility that the configuration did not go well (wrong filename, directory, …), you should check what certificate is provided by LinkAhead. When you open the URL with a browser and get a Security Warning, ask the browser to show the certificate (Firefox: Click on ‘Advanced…’ and then ‘View Certificate’ below the Error Code). If it simply says ‘localhost’ for Subject Name without any further Information like organization or state, it is probably the default self-signed certificate that is served by LinkAhead and the configuration is incorrect. Check paths and naming of files carefully.

Server cannot be reached

If for example a browser cannot establish a connection to the LinkAhead server, check the logs (e.g. journalctl -u linkahead -b). If you see the line java.io.IOException: keystore password was incorrect then the password to access the Java Key Store supplied to LinkAhead is incorrect. Check whether the file containing the password is in the server configuration folder and whether the password is spelled correctly.