sql-server-linux-configure-mssql-conf.md

title	description	author	ms.author	ms.date	ms.service	ms.subservice	ms.topic	ms.custom
Configure SQL Server Settings on Linux	This article describes how to use the mssql-conf tool to configure SQL Server settings on Linux.	rwestMSFT	randolphwest	04/09/2025	sql	linux	install-set-up-deploy	linux-related-content

Configure SQL Server on Linux with the mssql-conf tool

[!INCLUDE SQL Server - Linux]

::: moniker range="=sql-server-linux-2017 || =sql-server-2017"

mssql-conf is a configuration script that installs with [!INCLUDE sssql17-md] for Red Hat Enterprise Linux, SUSE Linux Enterprise Server, and Ubuntu. It modifies the mssql.conf file where configuration values are stored. You can use mssql-conf utility to set the following parameters:

Parameter	Description
Agent	Enable [!INCLUDE ssnoversion-md] Agent.
Authenticate with Windows	Settings for Windows Server Active Directory authentication.
Collation	Set a new collation for [!INCLUDE ssnoversion-md] on Linux.
Customer feedback	Choose whether or not [!INCLUDE ssnoversion-md] sends feedback to Microsoft.
Database Mail Profile	Set the default database mail profile for [!INCLUDE ssnoversion-md] on Linux.
Default data directory	Change the default directory for new [!INCLUDE ssnoversion-md] database data files (.mdf).
Default log directory	Changes the default directory for new [!INCLUDE ssnoversion-md] database log (.ldf) files.
Default master database directory	Changes the default directory for the master database and log files.
Default master database file name	Changes the name of master database files.
Default dump directory	Change the default directory for new memory dumps and other troubleshooting files.
Default error log directory	Changes the default directory for new [!INCLUDE ssnoversion-md] Error Log, Default Profiler Trace, System Health Session XE, and Hekaton Session XE files.
Default backup directory	Change the default directory for new backup files.
Dump type	Choose the type of dump memory dump file to collect.
Edition	Set the edition of [!INCLUDE ssnoversion-md].
High availability	Enable Availability Groups.
Local Audit directory	Set a directory to add Local Audit files.
Locale	Set the locale for [!INCLUDE ssnoversion-md] to use.
Memory limit	Set the memory limit for [!INCLUDE ssnoversion-md].
Network settings	Additional network settings for [!INCLUDE ssnoversion-md].
Microsoft Distributed Transaction Coordinator	Configure and troubleshoot MSDTC on Linux.
TCP port	Change the port where [!INCLUDE ssnoversion-md] listens for connections.
TLS	Configure Transport Level Security.
Trace flags	Set the trace flags that the service is going to use.

::: moniker-end

::: moniker range="=sql-server-linux-ver15 || =sql-server-ver15"

mssql-conf is a configuration script that installs with [!INCLUDE SQL Server 2019] for Red Hat Enterprise Linux, SUSE Linux Enterprise Server, and Ubuntu. You can use this utility to set the following parameters:

Parameter	Description
Agent	Enable [!INCLUDE ssnoversion-md] Agent
Authenticate with Windows	Settings for Windows Server Active Directory authentication.
Collation	Set a new collation for [!INCLUDE ssnoversion-md] on Linux.
Customer feedback	Choose whether or not [!INCLUDE ssnoversion-md] sends feedback to Microsoft.
Database Mail Profile	Set the default database mail profile for [!INCLUDE ssnoversion-md] on Linux.
Default data directory	Change the default directory for new [!INCLUDE ssnoversion-md] database data files (.mdf).
Default log directory	Changes the default directory for new [!INCLUDE ssnoversion-md] database log (.ldf) files.
Default master database file directory	Changes the default directory for the master database files on existing SQL installation.
Default master database file name	Changes the name of master database files.
Default dump directory	Change the default directory for new memory dumps and other troubleshooting files.
Default error log directory	Changes the default directory for new [!INCLUDE ssnoversion-md] Error Log, Default Profiler Trace, System Health Session XE, and Hekaton Session XE files.
Default backup directory	Change the default directory for new backup files.
Dump type	Choose the type of dump memory dump file to collect.
Edition	Set the edition of [!INCLUDE ssnoversion-md].
High availability	Enable Availability Groups.
Local Audit directory	Set a directory to add Local Audit files.
Locale	Set the locale for [!INCLUDE ssnoversion-md] to use.
Memory limit	Set the memory limit for [!INCLUDE ssnoversion-md].
Microsoft Distributed Transaction Coordinator	Configure and troubleshoot MSDTC on Linux.
Machine Learning Services EULAs	Accept R and Python EULAs for mlservices packages. Applies to [!INCLUDE sssql19-md] only.
Network settings	Additional network settings for [!INCLUDE ssnoversion-md].
outboundnetworkaccess	Enable outbound network access for Machine Learning Services R, Python, and Java extensions.
TCP port	Change the port where [!INCLUDE ssnoversion-md] listens for connections.
TLS	Configure Transport Level Security.
Trace flags	Set the trace flags that the service is going to use.

::: moniker-end

::: moniker range=">= sql-server-linux-ver16 || >= sql-server-ver16"

mssql-conf is a configuration script that installs with [!INCLUDE sssql22-md] for Red Hat Enterprise Linux, and Ubuntu. You can use this utility to set the following parameters:

Parameter	Description
Agent	Enable [!INCLUDE ssnoversion-md] Agent
Authenticate with Microsoft Entra ID	Settings for authenticating with Microsoft Entra ID (formerly Azure Active Directory).
Authenticate with Windows	Settings for Windows Server Active Directory authentication.
Collation	Set a new collation for [!INCLUDE ssnoversion-md] on Linux.
Customer feedback	Choose whether or not [!INCLUDE ssnoversion-md] sends feedback to Microsoft.
Database Mail Profile	Set the default database mail profile for [!INCLUDE ssnoversion-md] on Linux.
Default data directory	Change the default directory for new [!INCLUDE ssnoversion-md] database data files (.mdf).
Default log directory	Changes the default directory for new [!INCLUDE ssnoversion-md] database log (.ldf) files.
Default master database file directory	Changes the default directory for the master database files on existing SQL installation.
Default master database file name	Changes the name of master database files.
Default dump directory	Change the default directory for new memory dumps and other troubleshooting files.
Default error log directory	Changes the default directory for new [!INCLUDE ssnoversion-md] Error Log, Default Profiler Trace, System Health Session XE, and Hekaton Session XE files.
Default backup directory	Change the default directory for new backup files.
Dump type	Choose the type of dump memory dump file to collect.
Edition	Set the edition of [!INCLUDE ssnoversion-md].
High availability	Enable Availability Groups.
Local Audit directory	Set a directory to add Local Audit files.
Locale	Set the locale for [!INCLUDE ssnoversion-md] to use.
Memory limit	Set the memory limit for [!INCLUDE ssnoversion-md].
Microsoft Distributed Transaction Coordinator	Configure and troubleshoot MSDTC on Linux.
Machine Learning Services EULAs	Accept R and Python EULAs for mlservices packages. Applies to [!INCLUDE sssql19-md] only.
Network settings	Additional network settings for [!INCLUDE ssnoversion-md].
Outbound network access	Enable outbound network access for Machine Learning Services R, Python, and Java extensions.
SQL Server Connector	Configure logging level for [!INCLUDE ssnoversion-md] Connector.
TCP port	Change the port where [!INCLUDE ssnoversion-md] listens for connections.
TLS	Configure Transport Level Security.
Trace flags	Set the trace flags that the service is going to use.

::: moniker-end

Tip

Some of these settings can also be configured with environment variables. For more information, see Configure SQL Server settings with environment variables on Linux.

Usage tips

• For Always On Availability Groups and shared disk clusters, always make the same configuration changes on each node.

• For the shared disk cluster scenario, don't attempt to restart the mssql-server service to apply changes. [!INCLUDE ssnoversion-md] is running as an application. Instead, take the resource offline and then back online.

• These examples run mssql-conf by specifying the full path: /opt/mssql/bin/mssql-conf. If you choose to navigate to that path instead, run mssql-conf in the context of the current directory: ./mssql-conf.

• If you want to modify the mssql.conf file inside of a container, create a mssql.conf file on the host where you have the container running with your desired settings, and then redeploy your container. For example, the following addition to the mssql.conf file enables [!INCLUDE ssnoversion-md] Agent.

  [sqlagent]
  enabled = true

  You can deploy your container with the following commands:

  docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" \
  -p 5433:1433 --name sql1 \
  -v /container/sql1:/var/opt/mssql \
  -d mcr.microsoft.com/mssql/server:2019-latest

  [!CAUTION]
  [!INCLUDE password-complexity]

  For more information, see Create the config files to be used by the SQL Server container.

Enable SQL Server Agent

The sqlagent.enabled setting enables SQL Server Agent. By default, [!INCLUDE ssnoversion-md] Agent is disabled. If sqlagent.enabled isn't present in the mssql.conf settings file, then [!INCLUDE ssnoversion-md] internally assumes that [!INCLUDE ssnoversion-md] Agent is disabled.

To change this setting, use the following steps:

1. Enable the [!INCLUDE ssnoversion-md] Agent:

   sudo /opt/mssql/bin/mssql-conf set sqlagent.enabled true

2. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

Set the default Database Mail profile for SQL Server on Linux

The sqlagent.databasemailprofile allows you to set the default DB Mail profile for email alerts.

sudo /opt/mssql/bin/mssql-conf set sqlagent.databasemailprofile <profile_name>

SQL Agent error logs

The sqlagent.errorlogfile and sqlagent.errorlogginglevel settings allows you to set the SQL Agent log file path and logging level respectively.

sudo /opt/mssql/bin/mssql-conf set sqlagent.errorlogfile <path>

SQL Agent logging levels are bitmask values that equal:

• 1 = Errors
• 2 = Warnings
• 4 = Info

If you want to capture all levels, use 7 as the value.

sudo /opt/mssql/bin/mssql-conf set sqlagent.errorlogginglevel <level>

Configure Microsoft Entra authentication

Starting with [!INCLUDE sssql22-md], you can configure Microsoft Entra ID for [!INCLUDE ssnoversion-md]. To configure Microsoft Entra ID, you must install the Azure extension for [!INCLUDE ssnoversion-md] following the installation of [!INCLUDE ssnoversion-md]. For information on how to configure Microsoft Entra ID, see Tutorial: Set up Microsoft Entra authentication for SQL Server.

Change the default Microsoft Entra ID certificate path

By default, the Microsoft Entra certificate file is stored in /var/opt/mssql/aadsecrets/. You can change this path if you use a certificate store or an encrypted drive. To change the path, you can use the following command:

sudo /opt/mssql/bin/mssql-conf set network.aadcertificatefilepath /path/to/new/location.pfx

In the previous example, /path/to/new/location.pfx is your preferred path including the certificate name.

The certificate for Microsoft Entra authentication, downloaded by the Azure extension for [!INCLUDE ssnoversion-md], is stored at this location. You can't change it to /var/opt/mssql/secrets.

Note

The default Microsoft Entra ID certificate path can be changed at any time after [!INCLUDE ssnoversion-md] is installed, but must be changed before enabling Microsoft Entra ID.

Microsoft Entra ID configuration options

The following options are used by Microsoft Entra authentication for an instance of [!INCLUDE ssnoversion-md] running on Linux.

Warning

Microsoft Entra ID parameters are configured by the Azure extension for [!INCLUDE ssnoversion-md], and shouldn't be reconfigured manually. They are listed here for informational purposes.

[!INCLUDE sssql22-md] CU 19 introduces an option to set the IPv6 records limit for Microsoft Entra authentication endpoints. If IPv6 is enabled on Linux, and the IPv6 addresses of the Microsoft Entra authentication endpoints aren't reachable, you can set the network.ipv6dnsrecordslimit option for Microsoft Entra authentication to work. Setting this option to any value between 0 and 5 guarantees that at least one IPv4 address is tried to reach the Microsoft Entra endpoints.

A value of 0 means that no IPv6 endpoint addresses are tried. A value of 5 means that five AAAA addresses are tried.

Note

This network.ipv6dnsrecordslimit setting is configured at the server level, and can affect other services that use IPv6.

Option	Description
network.aadauthenticationendpoint	Endpoint for Microsoft Entra authentication
network.aadcertificatefilepath	Path to certificate file for authenticating to Microsoft Entra ID
network.aadclientcertblacklist	Microsoft Entra ID Client Certificate blocklist
network.aadclientid	Microsoft Entra Client GUID
network.aadfederationmetadataendpoint	Endpoint for Microsoft Entra Federation Metadata
network.aadgraphapiendpoint	Endpoint for Azure AD Graph API
network.aadgraphendpoint	Azure AD Graph Endpoint
network.aadissuerurl	Microsoft Entra Issuer URL
network.aadmsgraphendpoint	Microsoft Entra MS Graph Endpoint
network.aadonbehalfofauthority	Microsoft Entra ID On Behalf of Authority
network.aadprimarytenant	Microsoft Entra Primary Tenant GUID
network.aadsendx5c	Microsoft Entra ID Send X5C
network.aadserveradminname	Name of the Microsoft Entra account that will be made sysadmin
network.aadserveradminsid	SID of the Microsoft Entra account that will be made sysadmin
network.aadserveradmintype	Type of the Microsoft Entra account that will be made sysadmin
network.aadserviceprincipalname	Microsoft Entra service principal name
network.aadserviceprincipalnamenoslash	Microsoft Entra service principal name, with no slash
network.aadstsurl	Microsoft Entra STS URL

Configure Windows Active Directory authentication

The setup-ad-keytab option can be used to create a keytab, but the user and Service Principal Names (SPNs) must have been created to use this option. The Active Directory utility, adutil can be used to create users, SPNs, and keytabs.

For options on using setup-ad-keytab, run the following command:

sudo /opt/mssql/bin/mssql-conf setup-ad-keytab --help

The validate-ad-config option validates the configuration for Active Directory authentication.

Change the SQL Server collation

The set-collation option changes the collation value to any of the supported collations. To make this change, the [!INCLUDE ssnoversion-md] service needs to be stopped.

1. First backup any user databases on your server.

2. Then use the sp_detach_db stored procedure to detach the user databases.

3. Run the set-collation option and follow the prompts:

   sudo /opt/mssql/bin/mssql-conf set-collation

4. The mssql-conf utility attempts to change to the specified collation value and restart the service. If there are any errors, it rolls back the collation to the previous value.

5. Restore your user database backups.

For a list of supported collations, run the sys.fn_helpcollations function: SELECT Name from sys.fn_helpcollations().

Configure customer feedback

The telemetry.customerfeedback setting changes whether [!INCLUDE ssnoversion-md] sends feedback to Microsoft or not. By default, this value is set to true for all editions. To change the value, run the following commands:

Important

You can not turn off customer feedback for free editions of [!INCLUDE ssnoversion-md], Express and Developer.

1. Run the mssql-conf script as root with the set command for telemetry.customerfeedback. The following example turns off customer feedback by specifying false.

   sudo /opt/mssql/bin/mssql-conf set telemetry.customerfeedback false

2. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

For more information, see Configure usage and diagnostic data collection for SQL Server on Linux and the SQL Server privacy supplement.

Change the default data or log directory location

The filelocation.defaultdatadir and filelocation.defaultlogdir settings change the location where the new database and log files are created. By default, this location is /var/opt/mssql/data. To change these settings, use the following steps:

1. Create the target directory for new database data and log files. The following example creates a new /tmp/data directory:

   sudo mkdir /tmp/data

2. Change the owner and group of the directory to the mssql user:

   sudo chown mssql /tmp/data
   sudo chgrp mssql /tmp/data

3. Use mssql-conf to change the default data directory with the set command:

   sudo /opt/mssql/bin/mssql-conf set filelocation.defaultdatadir /tmp/data

4. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

5. Now all the database files for the new databases created are stored in this new location. If you would like to change the location of the log (.ldf) files of the new databases, you can use the following set command:

   sudo /opt/mssql/bin/mssql-conf set filelocation.defaultlogdir /tmp/log

6. This command also assumes that a /tmp/log directory exists, and that it's under the user and group mssql.

Change the default master database file directory location

The filelocation.masterdatafile and filelocation.masterlogfile setting changes the location where the [!INCLUDE ssnoversion-md] [!INCLUDE ssde-md] looks for the master database files. By default, this location is /var/opt/mssql/data.

To change these settings, use the following steps:

1. Create the target directory for new error log files. The following example creates a new /tmp/masterdatabasedir directory:

   sudo mkdir /tmp/masterdatabasedir

2. Change the owner and group of the directory to the mssql user:

   sudo chown mssql /tmp/masterdatabasedir
   sudo chgrp mssql /tmp/masterdatabasedir

3. Use mssql-conf to change the default master database directory for the master data and log files with the set command:

   sudo /opt/mssql/bin/mssql-conf set filelocation.masterdatafile /tmp/masterdatabasedir/master.mdf
   sudo /opt/mssql/bin/mssql-conf set filelocation.masterlogfile /tmp/masterdatabasedir/mastlog.ldf

   [!NOTE]
   In addition to moving the master data and log files, this also moves the default location for all other system databases.

4. Stop the [!INCLUDE ssnoversion-md] service:

   sudo systemctl stop mssql-server

5. Move the master.mdf and mastlog.ldf files:

   sudo mv /var/opt/mssql/data/master.mdf /tmp/masterdatabasedir/master.mdf
   sudo mv /var/opt/mssql/data/mastlog.ldf /tmp/masterdatabasedir/mastlog.ldf

6. Start the [!INCLUDE ssnoversion-md] service:

   sudo systemctl start mssql-server

   [!NOTE]
   If [!INCLUDE ssnoversion-md] can't find master.mdf and mastlog.ldf files in the specified directory, a templated copy of the system databases is automatically created in the specified directory, and [!INCLUDE ssnoversion-md] successfully starts up. However, metadata such as user databases, server logins, server certificates, encryption keys, SQL agent jobs, or old sa password aren't updated in the new master database. You'll have to stop [!INCLUDE ssnoversion-md] and move your old master.mdf and mastlog.ldf to the new specified location and start [!INCLUDE ssnoversion-md] to continue using the existing metadata.

Change the name of master database files

The filelocation.masterdatafile and filelocation.masterlogfile setting changes the location where the [!INCLUDE ssnoversion-md] [!INCLUDE ssde-md] looks for the master database files. You can also use this to change the name of the master database and log files.

To change these settings, use the following steps:

1. Stop the [!INCLUDE ssnoversion-md] service:

   sudo systemctl stop mssql-server

2. Use mssql-conf to change the expected master database names for the master data and log files with the set command:

   sudo /opt/mssql/bin/mssql-conf set filelocation.masterdatafile /var/opt/mssql/data/masternew.mdf
   sudo /opt/mssql/bin/mssql-conf set filelocation.mastlogfile /var/opt/mssql/data/mastlognew.ldf

   [!IMPORTANT]
   You can only change the name of the master database and log files after [!INCLUDE ssnoversion-md] has started successfully. Before the initial run, [!INCLUDE ssnoversion-md] expects the files to be named master.mdf and mastlog.ldf.

3. Change the name of the master database data and log files:

   sudo mv /var/opt/mssql/data/master.mdf /var/opt/mssql/data/masternew.mdf
   sudo mv /var/opt/mssql/data/mastlog.ldf /var/opt/mssql/data/mastlognew.ldf

4. Start the [!INCLUDE ssnoversion-md] service:

   sudo systemctl start mssql-server

Change the default dump directory location

The filelocation.defaultdumpdir setting changes the default location where the memory and SQL dumps are generated whenever there's a crash. By default, these files are generated in /var/opt/mssql/log.

To set up this new location, use the following commands:

1. Create the target directory for new dump files. The following example creates a new /tmp/dump directory:

   sudo mkdir /tmp/dump

2. Change the owner and group of the directory to the mssql user:

   sudo chown mssql /tmp/dump
   sudo chgrp mssql /tmp/dump

3. Use mssql-conf to change the default data directory with the set command:

   sudo /opt/mssql/bin/mssql-conf set filelocation.defaultdumpdir /tmp/dump

4. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

Change the default error log file directory location

The filelocation.errorlogfile setting changes the location where the new error log, default profiler trace, system health session XE, and Hekaton session XE files are created. By default, this location is /var/opt/mssql/log. The directory in which the [!INCLUDE ssnoversion-md] error log file is set, becomes the default log directory for other logs.

To change these settings:

1. Create the target directory for new error log files. The following example creates a new /tmp/logs directory:

   sudo mkdir /tmp/logs

2. Change the owner and group of the directory to the mssql user:

   sudo chown mssql /tmp/logs
   sudo chgrp mssql /tmp/logs

3. Use mssql-conf to change the default error log filename with the set command:

   sudo /opt/mssql/bin/mssql-conf set filelocation.errorlogfile /tmp/logs/errorlog

4. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

The errorlog.numerrorlogs setting allows you to specify the number of error logs maintained before cycling the log.

Change the default backup directory location

The filelocation.defaultbackupdir setting changes the default location where the backup files are generated. By default, these files are generated in /var/opt/mssql/data.

To set up this new location, use the following commands:

1. Create the target directory for new backup files. The following example creates a new /tmp/backup directory:

   sudo mkdir /tmp/backup

2. Change the owner and group of the directory to the mssql user:

   sudo chown mssql /tmp/backup
   sudo chgrp mssql /tmp/backup

3. Use mssql-conf to change the default backup directory with the set command:

   sudo /opt/mssql/bin/mssql-conf set filelocation.defaultbackupdir /tmp/backup

4. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

Specify core dump settings

If an exception or crash occurs in one of the [!INCLUDE ssnoversion-md] processes, [!INCLUDE ssnoversion-md] creates a memory dump. Capturing a memory dump might take a long time and take up significant space. To save resources and avoid repeated memory dumps, you can disable automatic dump capture using the coredump.disablecoredump option.

sudo /opt/mssql/bin/mssql-conf set coredump.disablecoredump <true or false>

Users can still generate memory dumps manually when automatic core dump is disabled (coredump.disablecoredump set to true).

There are two options for controlling the type of memory dumps that [!INCLUDE ssnoversion-md] collects: coredump.coredumptype and coredump.captureminiandfull. These relate to the two phases of core dump capture.

The first phase capture is controlled by the coredump.coredumptype setting, which determines the type of dump file generated during an exception. The second phase is enabled when the coredump.captureminiandfull setting. If coredump.captureminiandfull is set to true, the dump file specified by coredump.coredumptype is generated, and a second mini dump is also generated. Setting coredump.captureminiandfull to false disables the second capture attempt.

1. Decide whether to capture both mini and full dumps with the coredump.captureminiandfull setting.

   sudo /opt/mssql/bin/mssql-conf set coredump.captureminiandfull <true or false>

   Default: false

2. Specify the type of dump file with the coredump.coredumptype setting.

   sudo /opt/mssql/bin/mssql-conf set coredump.coredumptype <dump_type>

   Default: miniplus

   The following table lists the possible coredump.coredumptype values.

   Type	Description
   mini	Mini is the smallest dump file type. It uses the Linux system information to determine threads and modules in the process. The dump contains only the host environment thread stacks and modules. It doesn't contain indirect memory references or globals.
   miniplus	MiniPlus is similar to mini, but it includes additional memory. It understands the internals of SQLPAL and the host environment, adding the following memory regions to the dump: - Various globals - All memory above 64 TB - All named regions found in /proc/$pid/maps - Indirect memory from threads and stacks - Thread information, including associated thread environment blocks (TEBs) and process environment blocks (PEBs) - Module information - VMM and VAD tree
   filtered	Filtered uses a subtraction-based design where all memory in the process is included unless specifically excluded. The design understands the internals of SQLPAL and the host environment, excluding certain regions from the dump.
   full	Full is a complete process dump that includes all regions located in /proc/$pid/maps. This isn't controlled by the coredump.captureminiandfull setting.

Edition

The edition of [!INCLUDE ssnoversion-md] can be changed using the set-edition option. To change the edition of [!INCLUDE ssnoversion-md], the [!INCLUDE ssnoversion-md] service first needs to be stopped. For more information on available [!INCLUDE ssnoversion-md] on Linux editions, see SQL Server editions.

High availability

The hadr.hadrenabled option enables availability groups on your [!INCLUDE ssnoversion-md] instance. The following command enables availability groups by setting hadr.hadrenabled to 1. You must restart [!INCLUDE ssnoversion-md] for the setting to take effect.

sudo /opt/mssql/bin/mssql-conf set hadr.hadrenabled  1
sudo systemctl restart mssql-server

For information on how this is used with availability groups, see the following two articles.

• Configure SQL Server Always On Availability Group for high availability on Linux
• Configure a SQL Server Availability Group for read-scale on Linux

Set local audit directory

The telemetry.userrequestedlocalauditdirectory setting enables Local Audit and lets you set the directory where the Local Audit logs are created.

1. Create a target directory for new Local Audit logs. The following example creates a new /tmp/audit directory:

   sudo mkdir /tmp/audit

2. Change the owner and group of the directory to the mssql user:

   sudo chown mssql /tmp/audit
   sudo chgrp mssql /tmp/audit

3. Run the mssql-conf script as root with the set command for telemetry.userrequestedlocalauditdirectory:

   sudo /opt/mssql/bin/mssql-conf set telemetry.userrequestedlocalauditdirectory /tmp/audit

4. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

For more information, see Configure usage and diagnostic data collection for SQL Server on Linux.

Change the SQL Server locale

The language.lcid setting changes the [!INCLUDE ssnoversion-md] locale to any supported language identifier (LCID).

1. The following example changes the locale to French (1036):

   sudo /opt/mssql/bin/mssql-conf set language.lcid 1036

2. Restart the [!INCLUDE ssnoversion-md] service to apply the changes:

   sudo systemctl restart mssql-server

Set the memory limit

The memory.memorylimitmb setting controls the amount of physical memory (in MB) available to [!INCLUDE ssnoversion-md]. The default is 80% of the physical memory, to prevent out-of-memory (OOM) conditions.

Important

The memory.memorylimitmb setting limits the amount of physical memory available to the [!INCLUDE ssnoversion-md] process. The max server memory (MB) setting can be used to adjust the amount of memory available to the [!INCLUDE ssnoversion-md] buffer pool, but it can never exceed the amount of physical memory available to [!INCLUDE ssnoversion-md]. For more information about the max server memory (MB) server configuration option, see Server memory configuration options.

1. Run the mssql-conf script as root with the set command for memory.memorylimitmb. The following example changes the memory available to [!INCLUDE ssnoversion-md] to 3.25 GB (3,328 MB).

   sudo /opt/mssql/bin/mssql-conf set memory.memorylimitmb 3328

2. Restart the [!INCLUDE ssnoversion-md] service to apply the changes:

   sudo systemctl restart mssql-server

Additional memory settings

The following options are available to the memory settings.

Option	Description
memory.disablememorypressure	[!INCLUDE ssnoversion-md] disable memory pressure. Values can be true or false (default). Disabling memory pressure inhibits the signals [!INCLUDE ssnoversion-md] uses to limit its physical memory usage to memory.memorylimitmb, which causes the usage to eventually go beyond that limit.
memory.memory_optimized	Enable or disable [!INCLUDE ssnoversion-md] memory optimized features - persistent memory file enlightenment, memory protection. Values can be true or false.
memory.enablecontainersharedmemory	Applicable for [!INCLUDE ssnoversion-md] containers only. Use this setting to enable shared memory inside [!INCLUDE ssnoversion-md] containers. For more information, see ­Enable VDI backup and restore in containers. Values can be true or false (default).

Configure MSDTC

The network.rpcport and distributedtransaction.servertcpport settings are used to configure the Microsoft Distributed Transaction Coordinator (MSDTC). To change these settings, run the following commands:

1. Run the mssql-conf script as root with the set command for network.rpcport:

   sudo /opt/mssql/bin/mssql-conf set network.rpcport <rcp_port>

2. Then set the distributedtransaction.servertcpport setting:

   sudo /opt/mssql/bin/mssql-conf set distributedtransaction.servertcpport <servertcpport_port>

In addition to setting these values, you must also configure routing and update the firewall for port 135. For more information on how to do this, see How to configure the Microsoft Distributed Transaction Coordinator (MSDTC) on Linux.

There are several other settings for mssql-conf that you can use to monitor and troubleshoot MSDTC. The following table briefly describes these settings. For more information on their use, see the details in the Windows support article, Enable diagnostic tracing for MS DTC on a Windows 10 computer.

Option	Description
distributedtransaction.allowonlysecurerpccalls	Configure secure only RPC calls for distributed transactions
distributedtransaction.fallbacktounsecurerpcifnecessary	Configure security only RPC calls for distributed transactions
distributedtransaction.maxlogsize	DTC transaction log file size in MB. Default is 64 MB
distributedtransaction.memorybuffersize	Circular buffer size in which traces are stored. This size is in MB and default is 10 MB
distributedtransaction.servertcpport	MSDTC rpc server port
distributedtransaction.trace_cm	Traces in the connection manager
distributedtransaction.trace_contact	Traces the contact pool and contacts
distributedtransaction.trace_gateway	Traces Gateway source
distributedtransaction.trace_log	Log tracing
distributedtransaction.trace_misc	Traces that can't be categorized into the other categories
distributedtransaction.trace_proxy	Traces that are generated in the MSDTC proxy
distributedtransaction.trace_svc	Traces service and .exe file startup
distributedtransaction.trace_trace	The trace infrastructure itself
distributedtransaction.trace_util	Traces utility routines that are called from multiple locations
distributedtransaction.trace_xa	XA Transaction Manager (XATM) tracing source
distributedtransaction.tracefilepath	Folder in which trace files should be stored
distributedtransaction.turnoffrpcsecurity	Enable or disable RPC security for distributed transactions

::: moniker range=">=sql-server-linux-ver15 || >=sql-server-ver15"

Accept Machine Learning Services EULAs

Adding machine learning R or Python packages to the [!INCLUDE ssde-md] requires that you accept the licensing terms for open-source distributions of R and Python. The following table enumerates all available commands or options related to mlservices EULAs. The same EULA parameter is used for R and Python, depending on what you installed.

# For all packages: database engine and mlservices
# Setup prompts for mlservices EULAs, which you need to accept
sudo /opt/mssql/bin/mssql-conf setup

# Add R or Python to an existing installation
sudo /opt/mssql/bin/mssql-conf setup accept-eula-ml

# Alternative valid syntax
# Adds the EULA section to the INI and sets acceptulam to yes
sudo /opt/mssql/bin/mssql-conf set EULA accepteulaml Y

# Rescind EULA acceptance and removes the setting
sudo /opt/mssql/bin/mssql-conf unset EULA accepteulaml

You can also add EULA acceptance directly to the mssql.conf file:

[EULA]
accepteula = Y
accepteulaml = Y

::: moniker-end ::: moniker range=">=sql-server-linux-ver15 || >=sql-server-ver15"

Enable outbound network access

Outbound network access for R, Python, and Java extensions in the SQL Server Machine Learning Services feature is disabled by default. To enable outbound requests, set the outboundnetworkaccess Boolean property using mssql-conf.

After setting the property, restart [!INCLUDE ssnoversion-md] Launchpad service to read the updated values from the INI file. A restart message reminds you whenever an extensibility-related setting is modified.

# Adds the extensibility section and property.
# Sets "outboundnetworkaccess" to true.
# This setting is required if you want to access data or operations off the server.
sudo /opt/mssql/bin/mssql-conf set extensibility outboundnetworkaccess 1

# Turns off network access but preserves the setting
sudo /opt/mssql/bin/mssql-conf set extensibility outboundnetworkaccess 0

# Removes the setting and rescinds network access
sudo /opt/mssql/bin/mssql-conf unset extensibility.outboundnetworkaccess

You can also add outboundnetworkaccess directly to the mssql.conf file:

[extensibility]
outboundnetworkaccess = 1

::: moniker-end

Change logging level for SQL Server Connector for Azure Key Vault

In [!INCLUDE sssql22-md] CU 14 and later versions, [!INCLUDE ssnoversion-md] on Linux supports TDE Extensible Key Management with Azure Key Vault. You can set the logging level to one of the following values:

Level	Description
0 (default)	Information
1	Error
2	No log

To change the logging level for the [!INCLUDE ssnoversion-md] Connector, use the following example:

sudo /opt/mssql/bin/mssql-conf set sqlconnector.logginglevel 1

For more information, see Use SQL Server Connector with SQL Encryption Features.

Change the TCP port

The network.tcpport setting changes the TCP port where [!INCLUDE ssnoversion-md] listens for connections. By default, this port is set to 1433. To change the port, run the following commands:

1. Run the mssql-conf script as root with the set command for network.tcpport:

   sudo /opt/mssql/bin/mssql-conf set network.tcpport <new_tcp_port>

2. Restart the [!INCLUDE ssnoversion-md] service:

   sudo systemctl restart mssql-server

3. When connecting to [!INCLUDE ssnoversion-md] now, you must specify the custom port with a comma (,) after the hostname or IP address. For example, to connect with sqlcmd, you would use the following command:

   sqlcmd -S localhost,<new_tcp_port> -U test -P test

Specify TLS settings

The following options configure TLS for an instance of [!INCLUDE ssnoversion-md] running on Linux.

Option	Description
network.forceencryption	If 1, then [!INCLUDE ssNoVersion] forces all connections to be encrypted. By default, this option is 0.
network.tlscert	The absolute path to the certificate file that [!INCLUDE ssNoVersion] uses for TLS. Example: /etc/ssl/certs/mssql.pem The certificate file must be accessible by the mssql account. Microsoft recommends restricting access to the file using chown mssql:mssql <file>; chmod 400 <file>.
network.tlskey	The absolute path to the private key file that [!INCLUDE ssNoVersion] uses for TLS. Example: /etc/ssl/private/mssql.key The certificate file must be accessible by the mssql account. Microsoft recommends restricting access to the file using chown mssql:mssql <file>; chmod 400 <file>.
network.tlsprotocols	A comma-separated list of which TLS protocols are allowed by [!INCLUDE ssnoversion-md]. [!INCLUDE ssNoVersion] always attempts to negotiate the strongest allowed protocol. If a client doesn't support any allowed protocol, [!INCLUDE ssNoVersion] rejects the connection attempt. For compatibility, all supported protocols are allowed by default (1.2, 1.1, 1.0). If your clients support TLS 1.2, Microsoft recommends allowing only TLS 1.2.
network.tlsciphers	Specifies which ciphers are allowed by [!INCLUDE ssNoVersion] for TLS. This string must be formatted per OpenSSL's cipher list format. In general, you shouldn't need to change this option. By default, the following ciphers are allowed: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA
network.kerberoskeytabfile	Path to the Kerberos keytab file

For an example of using the TLS settings, see Encrypt connections to SQL Server on Linux.

Network settings

See Tutorial: Use Active Directory authentication with SQL Server on Linux for comprehensive information on using Active Directory authentication with [!INCLUDE ssnoversion-md] on Linux.

The following options are additional network settings configurable using mssql-conf.

Option	Description
network.disablesssd	Disable querying SSSD for Active Directory account information and default to LDAP calls. Values can be true or false.
network.enablekdcfromkrb5conf	Enable looking up KDC information from krb5.conf. Values can be true or false.
network.forcesecureldap	Force using LDAPS to contact domain controller. Values can be true or false.
network.ipaddress	IP address for incoming connections.
network.kerberoscredupdatefrequency	Time in seconds between checks for kerberos credentials that need to be updated. Value is an integer.
network.privilegedadaccount	Privileged Active Directory user to use for Active Directory authentication. Value is <username>. For more information, see Tutorial: Use Active Directory authentication with SQL Server on Linux
network.ipv6dnsrecordslimit	Set a configurable limit to the number of AAAA records returned by DNS requests. Value is a positive integer between 0 and 5. This option is guarantees that WinHTTP requests with the default number of retries (6) attempt at least one IPv4 address.
uncmapping	Maps UNC path to a local path. For example, sudo /opt/mssql/bin/mssql-conf set uncmapping //servername/sharename /tmp/folder.
ldaphostcanon	Set whether OpenLDAP should canonicalize hostnames during the bind step. Values can be true or false.

Enable or disable trace flags

The traceflag option enables or disables trace flags for the startup of the [!INCLUDE ssnoversion-md] service. To enable/disable a trace flag, use the following commands:

1. Enable a trace flag using the following command. For example, for Trace Flag 1234:

   sudo /opt/mssql/bin/mssql-conf traceflag 1234 on

2. You can enable multiple trace flags by specifying them separately:

   sudo /opt/mssql/bin/mssql-conf traceflag 2345 3456 on

3. In a similar way, you can disable one or more enabled trace flags by specifying them and adding the off parameter:

   sudo /opt/mssql/bin/mssql-conf traceflag 1234 2345 3456 off

4. Restart the [!INCLUDE ssnoversion-md] service to apply the changes:

   sudo systemctl restart mssql-server

Remove a setting

To unset any setting made with mssql-conf set, call mssql-conf with the unset option and the name of the setting. This clears the setting, effectively returning it to its default value.

1. The following example clears the network.tcpport option.

   sudo /opt/mssql/bin/mssql-conf unset network.tcpport

2. Restart the [!INCLUDE ssnoversion-md] service.

   sudo systemctl restart mssql-server

View current settings

To view any configured settings, run the following command to output the contents of the mssql.conf file:

sudo cat /var/opt/mssql/mssql.conf

Any settings not shown in this file are using their default values. The next section provides a sample mssql.conf file.

View various options

To view the various options that can be configured using the mssql-conf utility, run the help command:

sudo /opt/mssql/bin/mssql-conf --help

The results provide various configuration options and a short description for each of the settings.

mssql.conf format

The following /var/opt/mssql/mssql.conf file provides an example for each setting. You can use this format to manually make changes to the mssql.conf file as needed. If you do manually change the file, you must restart [!INCLUDE ssnoversion-md] before the changes are applied. To use the mssql.conf file with Docker, you must have Docker persist your data. First add a complete mssql.conf file to your host directory and then run the container. There's an example of this in Configure usage and diagnostic data collection for SQL Server on Linux.

::: moniker range="=sql-server-linux-2017 || =sql-server-2017"

[EULA]
accepteula = Y

[coredump]
captureminiandfull = true
coredumptype = full

[filelocation]
defaultbackupdir = /var/opt/mssql/data/
defaultdatadir = /var/opt/mssql/data/
defaultdumpdir = /var/opt/mssql/data/
defaultlogdir = /var/opt/mssql/data/

[hadr]
hadrenabled = 0

[language]
lcid = 1033

[memory]
memorylimitmb = 4096

[network]
forceencryption = 0
ipaddress = 10.192.0.0
kerberoskeytabfile = /var/opt/mssql/secrets/mssql.keytab
tcpport = 1401
tlscert = /etc/ssl/certs/mssql.pem
tlsciphers = ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA
tlskey = /etc/ssl/private/mssql.key
tlsprotocols = 1.2,1.1,1.0

[sqlagent]
databasemailprofile = default
errorlogfile = /var/opt/mssql/log/sqlagentlog.log
errorlogginglevel = 7

[telemetry]
customerfeedback = true
userrequestedlocalauditdirectory = /tmp/audit

[traceflag]
traceflag0 = 1204
traceflag1 = 2345
traceflag = 3456

::: moniker-end

::: moniker range=">=sql-server-linux-ver15 || >=sql-server-ver15"

[EULA]
accepteula = Y
accepteulaml = Y

[coredump]
captureminiandfull = true
coredumptype = full

[distributedtransaction]
servertcpport = 51999

[filelocation]
defaultbackupdir = /var/opt/mssql/data/
defaultdatadir = /var/opt/mssql/data/
defaultdumpdir = /var/opt/mssql/data/
defaultlogdir = /var/opt/mssql/data/

[hadr]
hadrenabled = 0

[language]
lcid = 1033

[memory]
memorylimitmb = 4096

[network]
forceencryption = 0
ipaddress = 10.192.0.0
kerberoskeytabfile = /var/opt/mssql/secrets/mssql.keytab
rpcport = 13500
tcpport = 1401
tlscert = /etc/ssl/certs/mssql.pem
tlsciphers = ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA:ECDHE-RSA-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA
tlskey = /etc/ssl/private/mssql.key
tlsprotocols = 1.2,1.1,1.0

[sqlagent]
databasemailprofile = default
errorlogfile = /var/opt/mssql/log/sqlagentlog.log
errorlogginglevel = 7

[telemetry]
customerfeedback = true
userrequestedlocalauditdirectory = /tmp/audit

[traceflag]
traceflag0 = 1204
traceflag1 = 2345
traceflag = 3456

::: moniker-end

Related content

• Configure SQL Server settings with environment variables on Linux
• Choose the right tool to manage SQL Server on Linux
• Configure and customize SQL Server Linux containers

[!INCLUDE contribute-to-content]