Install Devolutions Server for Linux

Devolutions Server is available for Linux with Microsoft Kestrel as the built-in web server and Microsoft PowerShell 7 for command-line installation. The present topic shows how to manually install Devolutions Server for Linux using Bash prompts and PowerShell scripts, as well as how to access and remove it.

Alternatively, Devolutions Server can be installed automatically using the scripts found on the Devolutions GitHub ScriptLibrary repository.

Installing prerequisites

1. If Microsoft SQL Server is not already installed, run the following Bash prompt with the MSSQL_SA_PASSWORD variable changed to a strong password:

   source /etc/os-release
   curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor --batch --yes -o /usr/share/keyrings/microsoft-prod.gpg
   curl -fsSL https://packages.microsoft.com/config/ubuntu/$VERSION_ID/mssql-server-2022.list | sudo tee /etc/apt/sources.list.d/mssql-server-2022.list
   sudo apt-get update
   sudo apt-get install -y mssql-server
   sudo MSSQL_SA_PASSWORD="mystrongpassword" MSSQL_PID="evaluation" /opt/mssql/bin/mssql-conf -n setup accept-eula
   sudo /opt/mssql/bin/mssql-conf set sqlagent.enabled true
   sudo systemctl restart mssql-server

   MSSQL_PID is set to evaluation in this example, but a product key can be entered here instead.

Microsoft only supports certain SQL versions. Refer to Microsoft's documentation to make sure your version of SQL is officially supported for your distribution.

1. Run this Bash prompt to install PowerShell 7:

   sudo apt-get update
   sudo apt-get install -y wget apt-transport-https software-properties-common
   source /etc/os-release
   wget -q https://packages.microsoft.com/config/ubuntu/$VERSION_ID/packages-microsoft-prod.deb
   sudo dpkg -i packages-microsoft-prod.deb
   rm packages-microsoft-prod.deb
   sudo apt-get update
   sudo apt-get install -y powershell

Ensure that the installation takes place in a directory that is accessible for the current user as the command line wget downloads a .deb package to said directory.

1. Choose whether to install the Devolutions.PowerShell module for the current user or all users.

   • For current user (location: /.local/share/powershell/Modules), run:

     Install-Module -Name 'Devolutions.PowerShell' -Confirm:$False

   • For all users (location: /opt/microsoft/powershell/7/Modules), run:

     & sudo pwsh -Command { Install-Module -Name 'Devolutions.PowerShell' -Confirm:$False -Scope 'AllUsers' -Force }

   A warning is likely to appear stating that the installation comes from an untrusted repository. The module is hosted on PowerShell Gallery, the official location for hosting PowerShell modules managed by Microsoft. To avoid seeing this warning in the future, run:

   Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

   Although not required, provisioning separate users and groups for Devolutions Server is highly recommended. Here is a Bash prompt to create a user and a group both named dvls with the installation directory set to /opt/devolutions/dvls:

   sudo useradd -N dvls
   sudo groupadd dvls
   sudo usermod -a -G dvls dvls
   # optional, add current user to dvls group
   sudo usermod -a -G dvls $(id -un)
   sudo mkdir -p /opt/devolutions/dvls
   sudo chown -R dvls:dvls /opt/devolutions/dvls
   sudo chmod 550 /opt/devolutions/dvls

Downloading and installing Devolutions Server for Linux

1. Run the PowerShell script below to download the latest version of Devolutions Server for Linux and extract the .tar.gz file into the /opt/devolutions/dvls location:

   $DVLSPath = "/opt/devolutions/dvls"
   $DVLSProductURL = "https://devolutions.net/productinfo.htm"
   
   $Result = (Invoke-RestMethod -Method 'GET' -Uri $DVLSProductURL) -Split "`r"
   
   $DVLSLinux = [PSCustomObject]@{
       "Version" = (($Result | Select-String DPSLinuxX64bin.Version) -Split "=")[-1].Trim()
       "URL"     = (($Result | Select-String DPSLinuxX64bin.Url) -Split "=")[-1].Trim()
       "Hash"    = (($Result | Select-String DPSLinuxX64bin.hash) -Split "=")[-1].Trim()
   }
   
   $DVLSDownloadPath = Join-Path -Path "/tmp" -ChildPath (([URI]$DVLSLinux.URL).Segments)[-1]
   
   Invoke-RestMethod -Method 'GET' -Uri $DVLSLinux.URL -OutFile $DVLSDownloadPath
   
   & tar -xzf $DVLSDownloadPath -C $DVLSPath --strip-components=1
   
   Remove-Item -Path $DVLSDownloadPath
   
   & sudo pwsh -Command {
     Param(
         $DVLSPath
     )
   
     chown -R dvls:dvls $DVLSPath
     chmod -R o-rwx $DVLSPath
     chmod 660 (Join-Path -Path $DVLSPath -ChildPath 'appsettings.json')
     chmod 770 (Join-Path -Path $DVLSPath -ChildPath 'App_Data')
     chown -R dvls:dvls $DVLSPath
   } -Args $DVLSPath
   
   Set-Location -Path $DVLSPath

   It is best for Devolutions Server to be able to respond over TLS. If a certificate does not exist already, one can be quickly generated using this Bash prompt:

   cd /opt/devolutions/dvls
   
   openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout cert.key -out cert.crt -subj "/CN=MYHOST" -addext "subjectAltName=DNS:MYHOST"
   openssl pkcs12 -export -out cert.pfx -inkey cert.key -in cert.crt -passout pass:

   In the example above, the subjectAltName uses DNS:. To respond on an IP only, use IP: instead.

Note that the generated .pfx certificate does not have a password.

1. Using the Devolutions.PowerShell module, run installation for Devolutions Server via PowerShell. Make sure to customize the values listed here:

   • MYHOST
   • MSSQLHOST
   • DBUSERNAME
   • YOURSTRONGPASSWORD
   • MYEMAIL

   Import-Module -Name 'Devolutions.PowerShell'
   
   $DVLSPath = "/opt/devolutions/dvls"
   # Modify the $DVLSURI to use 'https' if using SSL
   $DVLSURI  = "http://MYHOST:5000/"
   
   $DVLSAdminUsername = 'dvls-admin'
   $DVLSAdminPassword = 'dvls-admin'
   $DVLSAdminEmail    = 'MYEMAIL'
   
   $Params = @{
       "DatabaseHost"           = "MSSQLHOST"
       "DatabaseName"           = "DSERVER"
       "DatabaseUserName"       = "DBUSERNAME"
       "DatabasePassword"       = "YOURSTRONGPASSWORD"
       "ServerName"             = "DSERVER"
       "AccessUri"              = $DVLSURI
       "HttpListenerUri"        = $DVLSURI
       "DPSPath"                = $DVLSPath
       "UseEncryptedconnection" = $False # Modify as needed
       "TrustServerCertificate" = $False # Modify as needed
       "EnableTelemetry"        = $True # Modify as needed
       "DisableEncryptConfig"   = $True
   }
   
   $Configuration = New-DPSInstallConfiguration @Params
   New-DPSAppsettings -Configuration $Configuration
   
   $Settings = Get-DPSAppSettings -ApplicationPath $DVLSPath
   
   New-DPSDatabase -ConnectionString $Settings.ConnectionStrings.LocalSqlServer
   Update-DPSDatabase -ConnectionString $Settings.ConnectionStrings.LocalSqlServer -InstallationPath $DVLSPath
   New-DPSDataSourceSettings -ConnectionString $Settings.ConnectionStrings.LocalSqlServer
   
   New-DPSEncryptConfiguration -ApplicationPath $DVLSPath
   New-DPSDatabaseAppSettings -Configuration $Configuration
   
   New-DPSAdministrator -ConnectionString $Settings.ConnectionStrings.LocalSqlServer -Name $DVLSAdminUsername -Password $DVLSAdminPassword -Email $DVLSAdminEmail

   If a certificate has already been generated, proceed to modify the appsettings.json file to allow Kestrel to respond over TLS using this PowerShell script:

   Import-Module -Name 'Devolutions.PowerShell'
   
   $DVLSPath = '/opt/devolutions/dvls'
   
   $JSON = Get-Content -Path (Join-Path -Path $DVLSPath -ChildPath 'appsettings.json') | ConvertFrom-JSON -Depth 100
   
   $JSON.Kestrel.Endpoints.Http | Add-Member -MemberType NoteProperty -Name 'Certificate' -Value @{
       'Path'     = (Join-Path -Path $DVLSPath -ChildPath 'cert.pfx')
       'Password' = ''
   }
   
   $JSON | ConvertTo-JSON -Depth 100 | Set-Content -Path (Join-Path -Path $DVLSPath -ChildPath 'appsettings.json')
   
   $Settings = Get-DPSAppSettings -ApplicationPath $DVLSPath
   
   $AccessUri = (Get-DPSAccessUri -ConnectionString $Settings.ConnectionStrings.LocalSqlServer).AccessUri
   Set-DPSAccessUri -ApplicationPath $DVLSPath -ConnectionString $Settings.ConnectionStrings.LocalSqlServer -AccessURI ($AccessUri -Replace "http","https")
   
   & sudo pwsh -Command {
     Param(
         $DVLSPath
     )
   
     & chown dvls:dvls (Join-Path -Path $DVLSPath -ChildPath 'cert.pfx')
   } -Args $DVLSPath

   To offer background running of Devolutions Server for Linux, it is recommended to create a unit file for systemd via this Bash prompt:

   sudo tee /etc/systemd/system/dvls.service > /dev/null <<EOT
   [Unit]
   Description=DVLS
   
   [Service]
   Type=simple
   Restart=always
   RestartSec=10
   User=dvls
   ExecStart=/opt/devolutions/dvls/Devolutions.Server
   WorkingDirectory=/opt/devolutions/dvls
   KillSignal=SIGINT
   SyslogIdentifier=dvls
   Environment="SCHEDULER_EMBEDDED=true"
   
   [Install]
   WantedBy=multi-user.target
   Alias=dvls.service
   EOT
   
   sudo systemctl daemon-reload

2. To start Devolutions Server, run:

   sudo systemctl start dvls
   
   # View status
   sudo systemctl status dvls

Accessing Devolutions Server for Linux

By default, Devolutions Server for Linux listens on port 5000 on the IP or hostname of the installation system, which most commonly looks like: http://MYHOST:5000. Be aware that OAuth errors may occur upon first launch when trying to access Devolutions Server from a unconfigured URL. If this is the case, add additional URIs to listen on, or modify the primary one by running the following script in PowerShell:

Import-Module -Name 'Devolutions.PowerShell'

$DVLSPath = "/opt/devolutions/dvls"

$Settings = Get-DPSAppSettings -ApplicationPath $DVLSPath
$ConnectionString = $Settings.ConnectionStrings.LocalSqlServer

Get-DPSAccessUri -ConnectionString $ConnectionString

Set-DPSAccessUri -ConnectionString $ConnectionString -ApplicationPath $DVLSPath -AccessURI 'http://10.10.0.20:5000/' -AdditionalAccessURIs @('http://ubuntu-2204:5000/')

If Devolutions Server remains inaccessible outside of the installed system, check if the requisite firewall ports are opened, by adding Uncomplicated Firewall to the prompt, for example: sudo ufw allow 5000.

Importing Devolutions Server encryption key

Export from an existing Windows installation

Import-Module -Name 'Devolutions.PowerShell
$existingDVLSInstance = 'C:\my\path\dvlsInstance\'
$destination = 'C:\other\path\encryption.config'
Export-DPSEncryptionKeys -ApplicationPath $existingDVLSInstance -Destination $destination

Import to new Linux installation

Import-Module -Name 'Devolutions.PowerShell
$newDvlsInstance = '/home/user/linuxDlvsInstance'
$keysToImport = '/path/to/encryption.config'
Import-DPSEncryptionKeys -ApplicationPath $newDvlsInstance -Filename $keysToImport

Updating Devolutions Server for Linux

Do not extract the new .tar.gz archive directly over /opt/devolutions/dvls. Doing so overwrites appsettings.json and encryption.config, which leaves the service unable to start and may make existing data undecryptable. Always follow the update method detailed on this page.

1. Backup the database. Here's how to do so for Microsoft SQL Server (Linux or remote):

   /opt/mssql-tools18/bin/sqlcmd -S <MSSQLHOST> -U <DBUSERNAME> -P '<PASSWORD>' -C \
     -Q "BACKUP DATABASE [DSERVER] TO DISK = N'/var/opt/mssql/data/DSERVER-$(date +%F-%H%M).bak' WITH INIT, COMPRESSION;"

   Full path to sqlcmd avoids "command not found" error in non-login shells where /etc/profile.d/mssql-tools.sh has not been sourced.

   -C trusts the server certificate (required for local SQL Server installs that use a self-signed certificate).

   Backup to a directory writable by the MSSQL user. /var/opt/mssql/data/ works out of the box.
2. Make sure the .bak file exists and is not empty before proceeding to the next step.
3. Stop the Devolutions Server service using the following script:

   sudo systemctl stop dvls.service
   sudo systemctl status dvls.service   # confirm inactive (dead)

4. Back up the installation and configuration files. Keep in mind that /opt/devolutions/dvls is in mode 550 and is owned by dvls:dvls, therefore the backup cmdlets must run as root. Start PowerShell with sudo pwsh, then paste this script:

   Import-Module Devolutions.PowerShell
   $DVLSPath        = '/opt/devolutions/dvls'
   $BackupBase      = "/var/backups/dvls/$(Get-Date -Format 'yyyy-MM-dd-HHmm')"
   $BackupConfig    = Join-Path $BackupBase 'config'
   $BackupInstall   = Join-Path $BackupBase 'installation'
   mkdir -p $BackupConfig $BackupInstall
   Backup-DPSConfigurationFiles -ApplicationPath $DVLSPath -BackupConfigurationPath $BackupConfig
   Backup-DPSInstallationFiles  -ApplicationPath $DVLSPath -BackupPath              $BackupInstall

   • Backup-DPSConfigurationFiles preserves: appsettings.json, web.config, and encryption.config.
   • Backup-DPSInstallationFiles preserves custom folders, anomaly detection folder, and any user-added assets.
5. Empty the install directory except for App_data, as it contains runtime state that survives upgrades. Use this script to do so:

   sudo find /opt/devolutions/dvls -mindepth 1 -maxdepth 1 ! -name 'App_Data' -exec rm -rf {} +
   sudo tar -xzf /tmp/DVLS.<version>.linux-x64.tar.gz -C /opt/devolutions/dvls --strip-components=1

   Use --strip-components only if the archive has a top-level folder.
6. Restore configuration and custom data. In this step, appsettings.json (DB connection string) and web.config are put back into the new installation. Since encryption.config was already preserved inside App_Data/ by step #5, Restore-DPSConfigurationFiles will not put it at the install root because that is not where it lives on Linux. Here is the restoration script:

   Restore-DPSCustomFolders            -BackupPath              $BackupInstall -ApplicationPath $DVLSPath
   Restore-DPSAnomalyDetectionFolder   -BackupPath              $BackupInstall -ApplicationPath $DVLSPath
   Restore-DPSConfigurationFiles       -BackupConfigurationPath $BackupConfig  -ApplicationPath $DVLSPath

7. Pull the connection strings from the restored appsettings.json:

   $ConnectionString = (Get-DPSAppSettings -ApplicationPath $DVLSPath).ConnectionStrings.LocalSqlServer
   Update-DPSDatabase -ConnectionString $ConnectionString -InstallationPath $DVLSPath

   Update-DPSDatabase prints no output on success. Verify that it worked by checking that the command returned exit code 0 and that, after starting the service in step #9, the journal shows Migration done with status Done entries with no [ERR] lines.
8. Re-apply ownership and permissions:

   sudo chown -R dvls:dvls /opt/devolutions/dvls
   sudo chmod 550 /opt/devolutions/dvls
   sudo chmod 660 /opt/devolutions/dvls/appsettings.json
   sudo chmod 770 /opt/devolutions/dvls/App_Data
   # If a certs/ directory is in use:
   [ -d /opt/devolutions/dvls/certs ] && sudo chmod 750 /opt/devolutions/dvls/certs

9. Start the service and check if it works correctly:

   sudo systemctl start dvls.service
   sudo systemctl status dvls.service
   sudo journalctl -u dvls.service -n 100 --no-pager

Troubleshooting

• Service won't start, appsettings.json missing or empty: restore from $BackupConfig/appsettings.json, repeat steps #8 and 9.
• Login works but entries fail to decrypt: encryption.config was not restored. Copy $BackupConfig/encryption.config into $DVLSPath/App_Data/, fix permissions (chown dvls:dvls and chmod 660), then restart.
• DB schema errors at runtime: Update-DPSDatabase was skipped or failed. Repeat step #7.
• Full rollback: stop the service (see step #3), empty /opt/devolutions/dvls except App_Data/ (step #5), copy the contents of $BackupInstall back into /opt/devolutions/dvls, restore appsettings.json from $BackupConfig, re-apply ownership and permissions from step #8, restore the DB from the .bak produced in step #1, then restart.

Removing Devolutions Server

To remove Devolutions Server, run the Bash prompt below and customize it for the system. This script relies on the DbaTools PowerShell module to facilitate the removal of the MSSQL database. It assumes localhost is the MSSQL installation and dvls the database name.

# Remove DVLS on Linux, adjust as necessary
& sudo systemctl stop dvls.service
& sudo rm /etc/systemd/system/dvls.service
& sudo rm -rf /opt/devolutions/dvls
& sudo userdel -r dvls
& sudo groupdel dvls

Import-Module dbatools
$Credential = Get-Credential

Set-DbaToolsInsecureConnection

Remove-DbaDatabase -SqlInstance localhost -SqlCredential $Credential -Database 'dvls' -Confirm:$False