# ServerUtil The ServerUtil executable is a helper program that can interact with a running Duplicati [Server](/duplicati-programs/server.md) instance. The main use-case for this program is to allow scripted or programmatic interactions with the server, without resorting to loading the web UI. The ServerUtil is a replacement for a contributed [duplicati\_client](https://github.com/Pectojin/duplicati-client) script that is no longer maintained. Bot approaches works by accessing the Duplicat server API and issuing the same requests as the user interface would otherwise do. The ServerUtil binaries are called `Duplicati.CommandLine.ServerUtil.exe` on Windows and `duplicati-server-util` on Linux and MacOS. ## Handling login The ServerUtil needs to authenticate with the Server, which requires a connection url and a password. To avoid needing this, the ServerUtil will attempt to read the [Server database](/database-and-storage/the-server-database.md) and obtain information from there. If this succeeds, the ServerUtil will automatically configure an authenticated session with the server, without needing additional input. By default, the ServerUtil will look for the database at the default path for the current user context, meaning that if you run Duplicati as a service, you should invoke ServerUtil as Administrat/root. If the default database path is not correct, you can specify the database path for each command with: ``` duplicati-server-util login --server-datafolder= ``` If the database is encrypted, write protected, or in some other way inacessible, the caller needs to provide both the url and the password on the commandline. If the tool is intended to be invoked from a script, it is possible to secure a [refresh token](/technical-details/server-authentication-model.md) by calling the login command: ``` duplicati-server-util login --password= --hosturl= ``` This will cause the ServerUtil to store a refresh token in the settings file, such that future operations do not need the password (but will still need the hosturl). To safeguard the token, it is possible to provide `--settings-encryption-key=` that will encrypt the settings file. The [secret provider](/security-and-secrets/using-the-secret-provider.md) can be used to further secure this key, or can be used to provide the password on the commandline. To revoke the stored refresh token, run the logout command with the host url: ``` duplicati-server-util logout --hosturl= ``` ## Working with backups To show the backups currently configured, run the `list-backups` command: ``` duplicati-server-util list-backups ``` Each backup configuration has a name and an ID associated with it. All operations that work on one or more backups will accept either the ID or the name the backup has in the server (case insensitive). Using the ID is prefered as that is stable across backup renames, but the name may be more convenient. Once you know the name or ID of a backup configuration, you can schedule the backup: ``` duplicati-server-util run ``` This will put the backup into the running queue and start the backup as soon as the queue is empty. With the backup ID or name, it is also possible to export the backup configuration for later use: ``` duplicati-server-util export --encryption-passphrase= ``` This will export the configuration to a local file, encrypted with [AESCrypt](/duplicati-programs/command-line-interface-cli-1/sharpaescrypt.md). If you do not supply a passphrase, the exported configuration will not include the passphrase or storage credentials. Use `--export-passwords=true` to force export the passwords to a plain-text file. You can later import a backup that was previously exported with the command: ``` duplicati-server-util import ``` Note that this will create a new backup with the same configuration, so make sure you have removed the previous backup configuration first. ## Pausing and resuming the server A common use for the ServerUtil is to pause and resume the server, which can be done to avoid running backups during peak hours. To pause the server, invoke the ServerUtil with a [duration value](/technical-details/option-formats.md#timespans-timestamps-and-durations): ``` duplicati-server-util pause 5m ``` This will cause the scheduler to pause and not issue new backups until 5 minutes has passed. If no duration is passed, the server will pause until resumed. To resume the server, run the following command: ``` duplicati-server-util resume ``` ## Changing the Server password As explained in the section on the [access password](/configuration-and-management/duplicati-access-password.md), it is possible to use the ServerUtil to change the password. In the general case, this can be done with access to the [server database](/database-and-storage/the-server-database.md), but in some cases it requires knowing the previous password. Change the password with the command: ``` duplicati-server-util change-password ``` Note that this will not revoke access that is already granted, as such [access lives in refresh and access tokens](/technical-details/server-authentication-model.md). Restart the Server with `--webservice-reset-jwt-config=true` as explained in the [Server](/duplicati-programs/server.md#configuring-the-server-password) section. ## Issuing a "forever token" The "`issue-forever-token`" command was added to Duplicati beta 2.1.0.3 and canary 2.0.102. All requests to the Duplicati server needs to be authenticated with a valid token. Usually the token is obtained by providing the password to the server and receiving a token in the response. For some advanced setups, especially when running Duplicati behind an authenticated proxy server. In such a setup, the Duplicati password is an unwanted "double authentication". In a setup where there is another layer of authentication, it is possible to issue a token that last 10 years, significantly longer than the 15 minutes regular tokens last. To prevent unintended usage of the feature, it requires three steps to configure: * Stop Duplicati and start `duplicati-server` with `--webservice-enable-forever-token=true` * Run the command: `duplicati-server-util issue-forever-token` * Stop Duplicati and start without `--webservice-enable-forever-token` The commandline option `--webservice-enable-forever-token` toggles the ability to issue the token. The API is implemented such that it will only issue a single token pr. server start. Once the API is enabled, the `server-util` can call the API and obtain the single token. If something goes wrong, you can restart the Server and try again. Once the token is obtained, it is **important** to remove the `--webservice-enable-forever-token` again, so regular users cannot issue such a token. With the token in hand, configure the proxy to attach the header to each request: ``` Authorization: Bearer ``` With this header present, all requests to Duplicati will be authenticated. If you need to revoke a forever token, start the server once with `--webservice-reset-jwt-config` which will immediately invalidate any issued token. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.duplicati.com/duplicati-programs/command-line-interface-cli-1/serverutil.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.