How to renew the S-Filer server certificate

This page describes how to replace the SSL/TLS certificate of the S-Filer server before it expires, and how to update the gateways and web interfaces so that they keep trusting the server.

The certificate covered here is the server's SSL/TLS private key: the key pair that secures the HTTPS connections from the gateways and web interfaces to the server (port 8088 by default). It is selected in the cfg.server.webserver.service.jetty.server.private.key configuration of the server instance.

Warning

The following certificates are separate and are not affected by this procedure:

• the Administrative Console certificate (port 8090 by default), see Renew the Administrative Console certificate;
• the HTTPS and FTPS certificates of the gateways (SSL private key of the gateway's HTTPS and FTPS protocols);
• the communication key of a gateway or web interface (Renew the key used to communicate with S-Filer Server link). Do not renew it: it is not related to the server certificate.

Why the gateways must be updated

Each gateway and web interface has a configuration file: sfiler.conf for the gateway and gui.conf for the web interface, both located in the conf directory of the gateway installation. These files contain, among others:

• cfg.sfiler.config.url: the URL of the server;
• cfg.sfiler.trusted.cert.1, cfg.sfiler.trusted.cert.2, ...: the certificates that the component trusts when it first connects to the server.

At startup, the gateway and the web interface connect to the server to retrieve their configuration. They only accept the server certificate if it is one of the cfg.sfiler.trusted.cert.* certificates, or if it is signed by one of them. If the new server certificate is not trusted, the component cannot start:

• the gateway logs Failed to initialize gateway. Could not bootstrap configuration with server.;
• the web interface logs The GUI could not get its configuration from the server at this moment. It will retry to get the configuration in 20 seconds. every 20 seconds.

The configuration files must therefore be regenerated after the server certificate is changed, then copied to every gateway.

Important

Changing the server certificate interrupts the service: the gateways and web interfaces cannot connect to the server until their configuration files are replaced and they are restarted. Plan a maintenance window and back up the conf directory of each gateway before you start.

See Also

To be notified before the certificates expire, configure the Certificate Expiration Notification task.

Prerequisites

• The list of all the host names used to reach the server, starting with the one in the server URL of the gateways (cfg.sfiler.config.url). The new certificate must cover all of them (see Host names and SNI host check).
• If you choose to import a certificate signed by a certificate authority (CA) (option A of step 1):
  • the new certificate and its private key in a PKCS#12 file (.p12 or .pfx) protected by a password. The file must contain a single private key, ideally with the complete certificate chain. JKS keystores are not supported;
  • the root certificate and any intermediate certificates, each in a separate .cer, .crt, .pem or .der file.
• Access to the server machine, and the credentials of the database account used by sfiler-config-cli.
• Access to every gateway machine, to replace the configuration files and restart the S-Filer Gateway service.
• The names of the gateway and web interface instances. To list them, run the list-components command.

The sfiler-config-cli commands below are run from the server installation directory (for example server).

Host names and SNI host check

The host names of the new certificate are checked twice:

• By the client: the gateways and web interfaces check that the host name of their server URL (cfg.sfiler.config.url) is in the certificate. Otherwise, they refuse the connection.
• By the server, when the SSL/TLS SNI host check option is enabled (default value: Yes). SNI (Server Name Indication) is the TLS extension by which a client indicates the host name it is connecting to. With this option, the server checks every HTTPS request: if the host name used by the client is not in the server certificate, the server rejects the request with an HTTP 400 Invalid SNI error. This prevents the server from answering under a name that its certificate does not cover.

The server considers that a host name is in the certificate if it matches:

• a DNS entry of the Subject Alternative Name (SAN), or the CN of the certificate;
• a wildcard name such as *.example.com, which covers a single level (sfiler.example.com, but not a.sfiler.example.com);
• an IP address entry of the SAN, if clients connect by IP address.

The SNI host check applies to every client of the server, including those that do not verify the certificate themselves: for example monitoring probes, load balancers, scripts or integrations that call the server API directly. If the old certificate covered several names (short name, fully qualified name, alias, IP address), list the names actually used and make sure that the new certificate covers them all. Otherwise, these clients receive the Invalid SNI error once the server is restarted (step 4).

To check whether the option is enabled, open [server name] > Configuration > Basic Configurations and look at SSL/TLS SNI host check.

Warning

Do not disable the SNI host check to work around a certificate that does not cover all the host names: get a certificate that covers them instead. If you must disable it temporarily, set SSL/TLS SNI host check to No, then restart the server. Enable it again once the certificate is corrected.

Step 1: Add the new certificate

Add the new key pair under a new alias, for example an alias that contains the year. Keeping the old key pair under its own alias allows you to roll back (see Rollback).

Choose one of the two options below:

• Option A: import a certificate signed by a CA, for example your organization's CA. Use this option if your security policy requires it.
• Option B: generate a self-signed certificate with sfiler-config-cli. No file is needed, but the certificate covers a single host name.

Option A: Import a certificate signed by a CA

Import the PKCS#12 file that contains the new certificate and its private key:

Linux

./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" import-certificate-file -a "server-tls-2026" -f /path/to/new-server-certificate.p12 -pw "certificate-password"

Windows

.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" import-certificate-file -a "server-tls-2026" -f C:\path\to\new-server-certificate.p12 -pw "certificate-password"

Then import the root certificate and the intermediate certificates of the CA as trusted certificates, if they are not already in the certificate manager. Each one needs its own alias.

Linux

./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" import-certificate-file -a "my-root-ca" -f /path/to/root-ca.cer
./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" import-certificate-file -a "my-intermediate-ca" -f /path/to/intermediate-ca.cer

Windows

.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" import-certificate-file -a "my-root-ca" -f C:\path\to\root-ca.cer
.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" import-certificate-file -a "my-intermediate-ca" -f C:\path\to\intermediate-ca.cer

All the trusted certificates of the certificate manager are written to the configuration files of the gateways. Importing the CA certificates explicitly ensures that the gateways trust the complete chain of the new certificate.

To check the result, run list-certificates with -t KEY_PAIR, then with -t TRUSTED_CERTIFICATE.

You can also import these files in the Administrative Console, under Certificate Management.

See Also

import-certificate-file

Option B: Generate a self-signed certificate

Generate a new RSA key pair with the generate-key-pair command:

• -h: the host name of the server, exactly as it appears in the cfg.sfiler.config.url URL of the gateways;
• -ks: the key size, 2048 or 4096;
• -d: the validity period in years, from 1 to 10.

Linux

./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" generate-key-pair -a "server-tls-2026" -h "sfiler-server.example.com" -ks 4096 -d 2

Windows

.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" generate-key-pair -a "server-tls-2026" -h "sfiler-server.example.com" -ks 4096 -d 2

The generated certificate is self-signed and only contains the host name in its CN: it has no certificate chain and no Subject Alternative Name. The gateways and web interfaces trust it as soon as they receive their new configuration file (step 3).

Because the certificate covers a single host name, all the clients of the server must use this exact name. If the server is reached under several names and the SNI host check is enabled, use option A with a certificate whose SAN lists all the names (see Host names and SNI host check).

Warning

sfiler-config-cli cannot produce a certificate signing request (CSR): a key generated by S-Filer cannot be signed by a CA afterwards. Any other client that connects directly to the server must also be configured to trust this self-signed certificate.

Step 2: Assign the new certificate to the server

In the Administrative Console:

1. Open [server name] > Configuration > Basic Configurations.
2. In SSL/TLS private key, select the alias imported in step 1, then click Save.
3. A confirmation message reminds you that the configuration files of all the gateways (sfiler.conf) and web interfaces (gui.conf) must be updated. Confirm.

You can also run the set-config command, where -n is the name of the server instance. The command does not check that the alias exists: make sure that it is spelled exactly as in step 1.

Linux

./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" set-config -n "mycompany_server" -k "cfg.server.webserver.service.jetty.server.private.key" -v "server-tls-2026"

Windows

.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" set-config -n "mycompany_server" -k "cfg.server.webserver.service.jetty.server.private.key" -v "server-tls-2026"

Step 3: Generate the new configuration files

For each gateway instance and each web interface instance, generate a new configuration file with the export-config command. The file contains the server URL, the trusted certificates (including the new server certificate) and the instance's own communication key.

To avoid mixing up the files, generate them in one directory per gateway machine:

Linux

./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" export-config -n "mycompany_gateway" -ccf /tmp/renewal/gateway1/sfiler.conf
./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" export-config -n "mycompany_gui" -ccf /tmp/renewal/gateway1/gui.conf

Windows

.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" export-config -n "mycompany_gateway" -ccf C:\renewal\gateway1\sfiler.conf
.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" export-config -n "mycompany_gui" -ccf C:\renewal\gateway1\gui.conf

Repeat these two commands for each gateway machine, with its own instance names.

You can also download the files in the Administrative Console: open [gateway name] and click Download Gateway configuration (sfiler.conf), then open [web interface name] and click Download Web Client configuration (gui.conf).

Warning

The generated file replaces the whole configuration file of the component. If properties were added manually to the current sfiler.conf or gui.conf of a gateway, compare the files and add them back to the new file.

These files contain the private key of the component: transfer them through a secure channel and delete the copies once the procedure is complete.

Optionally, check the syntax of each file with the validate-component-config command. This command does not test the connection to the server.

Step 4: Restart the server

The server loads its SSL/TLS certificate at startup. Restart the S-Filer Server service (Windows services manager, or systemctl restart sfiler.service on Linux).

From this moment, the gateways and web interfaces that still use their old configuration file may no longer be able to connect.

Step 5: Update each gateway

On each gateway machine:

1. Stop the S-Filer Gateway service (Windows services manager, or systemctl stop sfiler-gateway.service on Linux).
2. Back up the current conf/sfiler.conf and conf/gui.conf files of the gateway installation directory.
3. Replace them with the files generated for this gateway in step 3.
4. Start the S-Filer Gateway service.

Step 6: Validate

1. In the logs of each gateway, check that the errors described in Why the gateways must be updated do not appear. If the logs show an HTTP 400 Invalid SNI error, the host name of the gateway's server URL is not in the new certificate (see Host names and SNI host check).
2. Open the web interface of each gateway in a browser and log in.
3. If the gateway uses them, test a transfer with each protocol (SFTP, FTPS, HTTPS).

Step 7: Delete the old certificate

Once the new certificate is validated on all the gateways, delete the old key pair with the delete-certificate command, or in Certificate Management. The deletion is refused while the alias is still in use.

Linux

./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" delete-certificate -a "server-tls-2025"

Windows

.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" delete-certificate -a "server-tls-2025"

Rollback

If the gateways cannot connect with the new certificate:

1. Select the old alias in SSL/TLS private key again (step 2), then restart the server.
2. On each gateway, stop the service, restore the sfiler.conf and gui.conf files backed up in step 5, then start the service.

Renew the Administrative Console certificate

The Administrative Console uses its own certificate, which is stored in the server's conf/sfiler.conf file. Replacing it does not require any change on the gateways.

The Administrative Console has its own SSL/TLS SNI host check option, enabled by default: the new certificate must cover the host name typed in the browser's address bar to reach the console, otherwise the browser receives an Invalid SNI error.

Import the new key pair and assign it to the Administrative Console with the -apply-configurator option, which points to the server's configuration file, then restart the S-Filer Server service:

Linux

./sfiler-config-cli.sh -l my-user -p my-password -cf "conf/sfiler.conf" import-certificate-file -a "console-tls-2026" -f /path/to/new-console-certificate.p12 -pw "certificate-password" -apply-configurator "conf/sfiler.conf"

Windows

.\sfiler-config-cli.bat -l my-user -p my-password -cf "conf\sfiler.conf" import-certificate-file -a "console-tls-2026" -f C:\path\to\new-console-certificate.p12 -pw "certificate-password" -apply-configurator "conf\sfiler.conf"

You can also select the new key in Administrative Console > SSL/TLS private key (see Configuring the private key in the Administrative Console).