Skip to content

sql-server-linux-troubleshooting-guide.md

Latest commit

 

History

History
235 lines (154 loc) · 11.1 KB

sql-server-linux-troubleshooting-guide.md

File metadata and controls

235 lines (154 loc) · 11.1 KB
title Troubleshoot SQL Server on Linux
description Troubleshoot Microsoft SQL Server running on Linux or in a Docker container. Learn where to find information about supported features and known limitations.
author VanMSFT
ms.author vanto
ms.reviewer rwestMSFT
ms.date 02/24/2022
ms.topic troubleshooting
ms.prod sql
ms.technology linux

Troubleshoot [!INCLUDEssNoVersion] on Linux

[!INCLUDE SQL Server - Linux]

This article describes how to troubleshoot Microsoft [!INCLUDEssNoVersion] running on Linux or in a Docker container. When troubleshooting [!INCLUDEssNoVersion] on Linux, remember to review the supported features and known limitations in the SQL Server on Linux Release Notes.

Tip

For answers to frequently asked questions, see the SQL Server on Linux FAQ.

Troubleshoot connection failures

If you have difficulty connecting to your Linux [!INCLUDEssNoVersion] instance, there are a few things to check.

  • If you're unable to connect locally using localhost, try using the IP address 127.0.0.1 instead. It's possible that localhost isn't properly mapped to this address.

  • Verify that the server name or IP address is reachable from your client machine.

    [!TIP] To find the IP address of your Ubuntu machine, you can run the ifconfig command as in the following example:

    sudo ifconfig eth0 | grep 'inet addr'

    For Red Hat, you can use the ip addr command as in the following example:

    sudo ip addr show eth0 | grep "inet"

    One exception to this technique relates to Azure VMs. For Azure VMs, find the public IP for the VM in the Azure portal.

  • If applicable, check that you opened the [!INCLUDEssNoVersion] port (default 1433) on the firewall.

  • For Azure VMs, check that you have a network security group rule for the default SQL Server port.

  • Verify that the user name and password don't contain any typos, extra spaces, or incorrect casing.

  • Try to explicitly set the protocol and port number with the server name like the following example: tcp:servername,1433.

  • Network connectivity issues can also cause connection errors and timeouts. After verifying your connection information and network connectivity, try the connection again.

Manage the [!INCLUDEssNoVersion] service

The following section shows how to manage the execution of [!INCLUDEssNoVersion] Docker containers. To manage services for Linux, see Start, stop, and restart SQL Server services on Linux.

Manage the execution of the [!INCLUDEssNoVersion] Docker container

You can get the status and container ID of the latest created [!INCLUDEssNoVersion] Docker container by running the following command (The ID is under the CONTAINER ID column):

sudo docker ps -l

You can stop or restart the [!INCLUDEssNoVersion] service as needed using the following commands:

sudo docker stop <container ID>
sudo docker restart <container ID>

Tip

For more troubleshooting tips for Docker, see Troubleshooting SQL Server Docker containers.

Access the log files

The [!INCLUDEssNoVersion] [!INCLUDEssDE] logs to the /var/opt/mssql/log/errorlog file in both the Linux and Docker installations. You need to be in 'superuser' mode to browse this directory.

The installer logs here: /var/opt/mssql/setup-<time stamp representing time of install> You can browse the errorlog files with any UTF-16 compatible tool like vim or cat like this:

sudo cat errorlog

If you prefer, you can also convert the files to UTF-8 to read them with more or less with the following command:

sudo iconv -f UTF-16LE -t UTF-8 <errorlog> -o <output errorlog file>

Extended events

Extended events can be queried via a SQL command. More information about extended events can be found here:

Crash dumps

Look for dumps in the log directory in Linux. Check under the /var/opt/mssql/log directory for Linux Core dumps (.tar.gz2 extension) or SQL minidumps (.mdmp extension)

For Core dumps

sudo ls /var/opt/mssql/log | grep .tar.gz2

For SQL dumps

sudo ls /var/opt/mssql/log | grep .mdmp

Start [!INCLUDEssNoVersion] in minimal configuration or in single user mode

Start [!INCLUDEssNoVersion] in minimal configuration mode

This mode is useful if the setting of a configuration value (for example, over-committing memory) has prevented the server from starting.

sudo -u mssql /opt/mssql/bin/sqlservr -f

Start [!INCLUDEssNoVersion] in single user mode

Sometimes you may have to start an instance of [!INCLUDEssNoVersion] in single-user mode by using the startup option -m. For example, you may want to change server configuration options or recover a damaged master database or other system database.

Start [!INCLUDEssNoVersion] in single user mode

sudo -u mssql /opt/mssql/bin/sqlservr -m

Start [!INCLUDEssNoVersion] in single user mode with sqlcmd

sudo -u mssql /opt/mssql/bin/sqlservr -m sqlcmd

Warning

Start [!INCLUDEssNoVersion] on Linux with the mssql user to prevent future startup issues. For example: sudo -u mssql /opt/mssql/bin/sqlservr [STARTUP OPTIONS]

If you have accidentally started [!INCLUDEssNoVersion] with another user, you must change ownership of [!INCLUDEssNoVersion] database files back to the mssql user prior to starting [!INCLUDEssNoVersion] with systemd. For example, to change ownership of all database files under /var/opt/mssql to the mssql user, run the following command:

chown -R mssql:mssql /var/opt/mssql/

Rebuild system databases

As a last resort, you can choose to rebuild the master and model databases back to default versions.

Warning

These steps will delete all [!INCLUDEssNoVersion] system data that you have configured. This includes information about your user databases (but not the user databases themselves). It will also delete other information stored in the system databases, including the following: master key information, any certificates loaded in master, the SA Login password, job-related information from msdb, Database Mail information from msdb, and sp_configure options. Only use this step if you understand the implications.

  1. Stop [!INCLUDEssNoVersion] [!INCLUDEssDE]

    sudo systemctl stop mssql-server

  2. Run sqlservr with the force-setup parameter

    sudo -u mssql /opt/mssql/bin/sqlservr --force-setup

    [!WARNING] See the previous warning! Also, you must run this as the mssql user as shown here.

  3. After you see the message "Recovery is complete", press Ctrl+C. This will shut down [!INCLUDEssNoVersion].

  4. Reconfigure the SA password.

    sudo /opt/mssql/bin/mssql-conf set-sa-password

  5. Start [!INCLUDEssNoVersion] and reconfigure the server, including restoring or reattaching any user databases.

    sudo systemctl start mssql-server

Improve performance

Many factors affect performance, including database design, hardware, and workload demands. If you're looking to improve performance, start by reviewing the best practices in the article, Performance best practices and configuration guidelines for SQL Server on Linux. Then explore some of the available tools for troubleshooting performance problems.

Common issues

  1. You can't connect to your remote [!INCLUDEssNoVersion] instance.

    See the troubleshooting section of the article, Connect to SQL Server on Linux.

  2. ERROR: Hostname must be 15 characters or less.

    This is a known issue that happens whenever the name of the machine that is trying to install the [!INCLUDEssNoVersion] package is longer than 15 characters. There are currently no workarounds other than changing the name of the machine. You can edit the hostname file and reboot the machine, which is explained in detail in the following website guide.

  3. Resetting the system administration (SA) password.

    If you forgot the system administrator (SA) password or need to reset it for some other reason, follow these steps.

    [!NOTE] The following steps stop the [!INCLUDEssNoVersion] service temporarily.

    Log into the host terminal, run the following commands and follow the prompts to reset the SA password:

    sudo systemctl stop mssql-server
sudo /opt/mssql/bin/mssql-conf setup

  4. Using special characters in password.

    If you use some characters in the [!INCLUDEssNoVersion] login password, you might need to escape them with a backslash when you use them on the Linux command line. For example, you must escape the dollar sign ($) anytime you use it in a terminal command/shell script:

    Does not work:

    sudo sqlcmd -S myserver -U sa -P Test$$

    Does work:

    sqlcmd -S myserver -U sa -P Test\$\$

    Resources: Special characters Escaping

[!INCLUDEGet Help Options]