Configure SQL Server on Linux with the mssql-conf tool
Applies to:
SQL Server - Linux
mssql-conf is a configuration script that installs with SQL Server 2017 (14.x) 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 SQL Server Agent. |
Authenticate with Windows | Settings for Windows Server Active Directory authentication. |
Collation | Set a new collation for SQL Server on Linux. |
Customer feedback | Choose whether or not SQL Server sends feedback to Microsoft. |
Database Mail Profile | Set the default database mail profile for SQL Server on Linux. |
Default data directory | Change the default directory for new SQL Server database data files (.mdf). |
Default log directory | Changes the default directory for new SQL Server 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 SQL Server 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 SQL Server. |
High availability | Enable Availability Groups. |
Local Audit directory | Set a directory to add Local Audit files. |
Locale | Set the locale for SQL Server to use. |
Memory limit | Set the memory limit for SQL Server. |
Network settings | Additional network settings for SQL Server. |
Microsoft Distributed Transaction Coordinator | Configure and troubleshoot MSDTC on Linux. |
TCP port | Change the port where SQL Server listens for connections. |
TLS | Configure Transport Level Security. |
Trace flags | Set the trace flags that the service is going to use. |
mssql-conf is a configuration script that installs with SQL Server 2019 (15.x) 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 SQL Server Agent |
Authenticate with Windows | Settings for Windows Server Active Directory authentication. |
Collation | Set a new collation for SQL Server on Linux. |
Customer feedback | Choose whether or not SQL Server sends feedback to Microsoft. |
Database Mail Profile | Set the default database mail profile for SQL Server on Linux. |
Default data directory | Change the default directory for new SQL Server database data files (.mdf). |
Default log directory | Changes the default directory for new SQL Server 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 SQL Server 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 SQL Server. |
High availability | Enable Availability Groups. |
Local Audit directory | Set a directory to add Local Audit files. |
Locale | Set the locale for SQL Server to use. |
Memory limit | Set the memory limit for SQL Server. |
Microsoft Distributed Transaction Coordinator | Configure and troubleshoot MSDTC on Linux. |
Machine Learning Services EULAs | Accept R and Python EULAs for mlservices packages. Applies to SQL Server 2019 (15.x) only. |
Network settings | Additional network settings for SQL Server. |
outboundnetworkaccess | Enable outbound network access for Machine Learning Services R, Python, and Java extensions. |
TCP port | Change the port where SQL Server listens for connections. |
TLS | Configure Transport Level Security. |
Trace flags | Set the trace flags that the service is going to use. |
mssql-conf is a configuration script that installs with SQL Server 2022 (16.x) for Red Hat Enterprise Linux, and Ubuntu. You can use this utility to set the following parameters:
Parameter | Description |
---|---|
Agent | Enable SQL Server 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 SQL Server on Linux. |
Customer feedback | Choose whether or not SQL Server sends feedback to Microsoft. |
Database Mail Profile | Set the default database mail profile for SQL Server on Linux. |
Default data directory | Change the default directory for new SQL Server database data files (.mdf). |
Default log directory | Changes the default directory for new SQL Server 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 SQL Server 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 SQL Server. |
High availability | Enable Availability Groups. |
Local Audit directory | Set a directory to add Local Audit files. |
Locale | Set the locale for SQL Server to use. |
Memory limit | Set the memory limit for SQL Server. |
Microsoft Distributed Transaction Coordinator | Configure and troubleshoot MSDTC on Linux. |
Machine Learning Services EULAs | Accept R and Python EULAs for mlservices packages. Applies to SQL Server 2019 (15.x) only. |
Network settings | Additional network settings for SQL Server. |
Outbound network access | Enable outbound network access for Machine Learning Services R, Python, and Java extensions. |
SQL Server Connector | Configure logging level for SQL Server Connector. |
TCP port | Change the port where SQL Server listens for connections. |
TLS | Configure Transport Level Security. |
Trace flags | Set the trace flags that the service is going to use. |
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. SQL Server 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 amssql.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 themssql.conf
file enables SQL Server Agent.[sqlagent] enabled = true
You can deploy your container with the following commands:
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<YourStrong@Passw0rd>" \ -p 5433:1433 --name sql1 \ -v /container/sql1:/var/opt/mssql \ -d mcr.microsoft.com/mssql/server:2019-latest
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, SQL Server Agent is disabled. If sqlagent.enabled
isn't present in the mssql.conf settings file, then SQL Server internally assumes that SQL Server Agent is disabled.
To change this setting, use the following steps:
Enable the SQL Server Agent:
sudo /opt/mssql/bin/mssql-conf set sqlagent.enabled true
Restart the SQL Server 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
= Errors2
= Warnings4
= 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 SQL Server 2022 (16.x), you can configure Microsoft Entra ID for SQL Server. To configure Microsoft Entra ID, you must install the Azure extension for SQL Server following the installation of SQL Server. 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 SQL Server, 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 SQL Server 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 SQL Server running on Linux.
Warning
Microsoft Entra ID parameters are configured by the Azure extension for SQL Server, and shouldn't be reconfigured manually. They are listed here for informational purposes.
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 SQL Server service needs to be stopped.
First backup any user databases on your server.
Then use the sp_detach_db stored procedure to detach the user databases.
Run the
set-collation
option and follow the prompts:sudo /opt/mssql/bin/mssql-conf set-collation
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.
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 SQL Server 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 SQL Server, Express and Developer.
Run the mssql-conf script as root with the
set
command fortelemetry.customerfeedback
. The following example turns off customer feedback by specifyingfalse
.sudo /opt/mssql/bin/mssql-conf set telemetry.customerfeedback false
Restart the SQL Server service:
sudo systemctl restart mssql-server
For more information, see Configure usage & 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:
Create the target directory for new database data and log files. The following example creates a new
/tmp/data
directory:sudo mkdir /tmp/data
Change the owner and group of the directory to the
mssql
user:sudo chown mssql /tmp/data sudo chgrp mssql /tmp/data
Use mssql-conf to change the default data directory with the
set
command:sudo /opt/mssql/bin/mssql-conf set filelocation.defaultdatadir /tmp/data
Restart the SQL Server service:
sudo systemctl restart mssql-server
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
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 SQL Server Database Engine looks for the master
database files. By default, this location is /var/opt/mssql/data
.
To change these settings, use the following steps:
Create the target directory for new error log files. The following example creates a new
/tmp/masterdatabasedir
directory:sudo mkdir /tmp/masterdatabasedir
Change the owner and group of the directory to the
mssql
user:sudo chown mssql /tmp/masterdatabasedir sudo chgrp mssql /tmp/masterdatabasedir
Use mssql-conf to change the default
master
database directory for the master data and log files with theset
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.
Stop the SQL Server service:
sudo systemctl stop mssql-server
Move the
master.mdf
andmastlog.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
Start the SQL Server service:
sudo systemctl start mssql-server
Note
If SQL Server can't find
master.mdf
andmastlog.ldf
files in the specified directory, a templated copy of the system databases is automatically created in the specified directory, and SQL Server successfully starts up. However, metadata such as user databases, server logins, server certificates, encryption keys, SQL agent jobs, or old SA login password aren't updated in the newmaster
database. You'll have to stop SQL Server and move your oldmaster.mdf
andmastlog.ldf
to the new specified location and start SQL Server 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 SQL Server Database Engine 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:
Stop the SQL Server service:
sudo systemctl stop mssql-server
Use mssql-conf to change the expected
master
database names for themaster
data and log files with theset
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 SQL Server has started successfully. Before the initial run, SQL Server expects the files to be namedmaster.mdf
andmastlog.ldf
.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
Start the SQL Server 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:
Create the target directory for new dump files. The following example creates a new
/tmp/dump
directory:sudo mkdir /tmp/dump
Change the owner and group of the directory to the
mssql
user:sudo chown mssql /tmp/dump sudo chgrp mssql /tmp/dump
Use mssql-conf to change the default data directory with the
set
command:sudo /opt/mssql/bin/mssql-conf set filelocation.defaultdumpdir /tmp/dump
Restart the SQL Server 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 SQL Server error log file is set, becomes the default log directory for other logs.
To change these settings:
Create the target directory for new error log files. The following example creates a new
/tmp/logs
directory:sudo mkdir /tmp/logs
Change the owner and group of the directory to the
mssql
user:sudo chown mssql /tmp/logs sudo chgrp mssql /tmp/logs
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
Restart the SQL Server 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:
Create the target directory for new backup files. The following example creates a new
/tmp/backup
directory:sudo mkdir /tmp/backup
Change the owner and group of the directory to the
mssql
user:sudo chown mssql /tmp/backup sudo chgrp mssql /tmp/backup
Use mssql-conf to change the default backup directory with the
set
command:sudo /opt/mssql/bin/mssql-conf set filelocation.defaultbackupdir /tmp/backup
Restart the SQL Server service:
sudo systemctl restart mssql-server
Specify core dump settings
If an exception or crash occurs in one of the SQL Server processes, SQL Server 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 SQL Server 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.
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
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 treefiltered
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 thecoredump.captureminiandfull
setting.
Edition
The edition of SQL Server can be changed using the set-edition
option. To change the edition of SQL Server, the SQL Server service first needs to be stopped. For more information on available SQL Server on Linux editions, see SQL Server editions.
High availability
The hadr.hadrenabled
option enables availability groups on your SQL Server instance. The following command enables availability groups by setting hadr.hadrenabled
to 1. You must restart SQL Server 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.
Create a target directory for new Local Audit logs. The following example creates a new
/tmp/audit
directory:sudo mkdir /tmp/audit
Change the owner and group of the directory to the
mssql
user:sudo chown mssql /tmp/audit sudo chgrp mssql /tmp/audit
Run the mssql-conf script as root with the
set
command fortelemetry.userrequestedlocalauditdirectory
:sudo /opt/mssql/bin/mssql-conf set telemetry.userrequestedlocalauditdirectory /tmp/audit
Restart the SQL Server service:
sudo systemctl restart mssql-server
For more information, see Configure usage & diagnostic data collection for SQL Server on Linux.
Change the SQL Server locale
The language.lcid
setting changes the SQL Server locale to any supported language identifier (LCID).
The following example changes the locale to French (1036):
sudo /opt/mssql/bin/mssql-conf set language.lcid 1036
Restart the SQL Server 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 SQL Server. 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 SQL Server process. The max server memory (MB) setting can be used to adjust the amount of memory available to the SQL Server buffer pool, but it can never exceed the amount of physical memory available to SQL Server. For more information about the max server memory (MB) server configuration option, see Server memory configuration options.
Run the mssql-conf script as root with the
set
command formemory.memorylimitmb
. The following example changes the memory available to SQL Server to 3.25 GB (3,328 MB).sudo /opt/mssql/bin/mssql-conf set memory.memorylimitmb 3328
Restart the SQL Server 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 |
SQL Server disable memory pressure. Values can be true or false (default). Disabling memory pressure inhibits the signals SQL Server 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 SQL Server memory optimized features - persistent memory file enlightenment, memory protection. Values can be true or false . |
memory.enablecontainersharedmemory |
Applicable for SQL Server containers only. Use this setting to enable shared memory inside SQL Server 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:
Run the mssql-conf script as root with the
set
command fornetwork.rpcport
:sudo /opt/mssql/bin/mssql-conf set network.rpcport <rcp_port>
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 |
Accept Machine Learning Services EULAs
Adding machine learning R or Python packages to the Database Engine 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
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 SQL Server 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
Change logging level for SQL Server Connector for Azure Key Vault
In SQL Server 2022 (16.x) CU 14 and later versions, SQL Server 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 SQL Server 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 SQL Server listens for connections. By default, this port is set to 1433. To change the port, run the following commands:
Run the mssql-conf script as root with the
set
command fornetwork.tcpport
:sudo /opt/mssql/bin/mssql-conf set network.tcpport <new_tcp_port>
Restart the SQL Server service:
sudo systemctl restart mssql-server
When connecting to SQL Server 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 SQL Server running on Linux.
Option | Description |
---|---|
network.forceencryption |
If 1, then SQL Server forces all connections to be encrypted. By default, this option is 0. |
network.tlscert |
The absolute path to the certificate file that SQL Server 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 SQL Server 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 SQL Server. SQL Server always attempts to negotiate the strongest allowed protocol. If a client doesn't support any allowed protocol, SQL Server 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 SQL Server 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 SQL Server 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 |
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 SQL Server service. To enable/disable a trace flag, use the following commands:
Enable a trace flag using the following command. For example, for Trace Flag 1234:
sudo /opt/mssql/bin/mssql-conf traceflag 1234 on
You can enable multiple trace flags by specifying them separately:
sudo /opt/mssql/bin/mssql-conf traceflag 2345 3456 on
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
Restart the SQL Server 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.
The following example clears the
network.tcpport
option.sudo /opt/mssql/bin/mssql-conf unset network.tcpport
Restart the SQL Server 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 SQL Server 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 & diagnostic data collection for SQL Server on Linux.
[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
[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
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
Contribute to SQL documentation
Did you know that you can edit SQL content yourself? If you do so, not only do you help improve our documentation, but you also get credited as a contributor to the page.
For more information, see How to contribute to SQL Server documentation