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.
You might want to restart LinkAhead to check if you setup the profile correctly:
$ systemctl restart linkahead
Systemd service
We already used the systemd service a couple of times. However, there is another
useful tool to interact with the LinkAhead server: The linkahead
script.
You can run
$ linkahead -h
to learn more about the available options.
Note, that you need to provide the path to the profile of the instance with which you want to interact. Using the above example creating a backup would look like this:
$ linkahead -p ~/.config/linkahead/profile.yml backup -d ~/linkahead_backup
Restore data
LinkAhead allows to restore data during start up. This can be enabled with the
restore: true
option in the profile.yml
. Corresponding files need to be
placed in custom/other/restore/
in the profile directory. A typical use case is
to place the files created with linkahead backup
here.
To disable restoring, set the option to false
and move the custom/other/restore/
folder to some other location.
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:
You have a valid certificate that you want to provide.
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.
Clients cannot connect
Make sure that your clients use the fully qualified domain name (e.g. linkahead.example.com
) in their configuration. The name must
equal the one of the certificate.
You may need to add the certificate of the CA (Certificate Authority) in the configuration of your client, if shipped with your operating system.
Accessibility
By default, the server will only listen on the loopback device (localhost
).
You can expand this by setting the bind_ip
value in the network
section of
profile.yml
. Specify the IP of the desired interface or use an empty string “”
(equivalent to 0.0.0.0
) to listen on all interfaces.
Envoy as reverse proxy
Envoy is needed in order to use components of the web interface that need to access the rather new GRPC API. Additionally, there are some further benefits from using a reverse proxy:
You can let Envoy do SSL termination. Thus you do not need to convert certificate files to the Java Key Store format any more, that is needed by the Java server.
All LinkAhead resources can be served under one port and Envoy distributes requests accordingly.
Envoy can be enabled by setting envoy_enabled: true
in profile.yml
. This will start an envoy
image together with LinkAhead.
Graphical Access Control Management
The WebUi comes with a graphical Access Control Management (ACM) module. This is currently
(2023-02-22) not enabled by default. To enable the ACM, set envoy_enabled: true
in your
profile.yml
and add BUILD_MODULE_EXT_ENTITY_ACL=ENABLED
in a file in
custom/caosdb-server/caosdb-webui/build.properties.d
.
Switching profiles
LinkAhead stores data persistently using Docker volumes. If you switch the profile and the new profile uses the same volumes, then changes are applied there and if the profile is set to restore an old data set, this will overwrite the data in the volume.
You can create a backup before switching such that you do not care about the data in
the Docker volume. Or you can set the most top level key in the profile.yml
of the profile that you want to switch to (by default it is
default
) to something else. You should then stop your first instance and start the second.
Standard profiles
You can try out a standard profile by stopping your current server (after creating a backup
if it contains something that should not get lost) and calling linkahead
with the -p
argument.
$ linkahead -p /usr/share/linkahead/profiles/demo/profile.yml start
The standard profiles in LinkAhead are:
default
The default
profile simply uses the defaults. This means, above all: no anonymous user,
persistent data, and authentication to the IndiScale server must be provided to obtain the Docker
images. This profile is a solid base to set up your own configuration in a production environment.
debug
The debug
profile is useful for writing scripts and tests, and for debugging. Debugging in the
server is enabled, the anonymous user is disabled and an empty database is loaded on every
restart.
demo
The demo
profile is the one which is used on the demo server at https://demo.indiscale.com.
It comes with customized content both for the database content and the web frontend, to provide user
interfaces and content for the demo tour. Because the server is restarted periodically, the profile
is set to restore its content upon startup. The anonymous user is enabled.