Active Directory Utility for SQL Server (ADUTIL) now officially supported with RHEL 9

July 16, 2024
Vivien Wang Arne Arnold Amit Khandelwal (Microsoft)
Related topics:
ContainersDatabasesLinux
Related products:
Microsoft SQL Server on Red Hat Enterprise LinuxRed Hat Enterprise Linux

As of June 2024, Active Directory Utility for SQL Server (ADUTIL) is now officially supported with RHEL 9. SQL Server 2022 has as of July 2024 been officially certified with RHEL 9, and is now Generally Available on Red Hat Ecosystem Catalog.

The adutil tool is a command-line interface (CLI) utility for configuring and managing Windows Active Directory domains for SQL Server on Linux and containers, without switching between Windows and Linux machines to manage Active Directory. This tool was developed to ensure that users get the most out of authentication, user management, and keytab configuration in a more integrated setting.

Does this all sound good to you? Let's dive in and find out how exactly we can set up adutil on Red Hat Enterprise Linux (RHEL) 9. 

Prepping and installing

You will need to join your host machine to the domain as a prerequisite—see Join SQL Server on Linux to Active Directory on how to get this all set up.

Then, to install adutil on RHEL 9, you’ll need to execute the following commands to add the RHEL 9 Prod repository:

sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/9/prod.repo 
## Now you are ready to install adutil using the command: 
sudo ACCEPT_EULA=Y yum install -y adutil 
## you can check the adutil version using the command and ensure the version is 1.1.138 
adutil --version

Use cases for adutil

Here are some of the typical activities that adutil is used for when configuring or administering Active Directory authentication for SQL Server on Linux and containers.

Creating an account in Active Directory:

adutil user create --name sqluser --distname CN=sqluser,CN=Users,DC=CONTOSO,DC=COM

Creating SPNs associated with an account or service:

adutil spn addauto -n sqluser -s MSSQLSvc -H mymachine.contoso.com -p 1433

Creating keytabs using adutil:

adutil keytab createauto -k /var/opt/mssql/secrets/mssql.keytab -p 1433 -H mymachine.contoso.com --password 'P@ssw0rd' -s MSSQLSvc

To navigate to the reference manual page, you can do so using the command man adutil.

To learn more about adutils check out Microsoft’s official documentation: Introduction to adutil - Active Directory Utility - SQL Server

Using adutil to manage Windows Active Directory

Let's go over some of the actions that you can perform using adutil. To see a list of top-level commands, type adutil --help. This command shows you the top-level commands that you can use to manage and interact with Active Directory:

$ adutil --help
adutil - A general AD utility
  Usage:
    adutil [account]
  Subcommands:
    account      Functions for generic account operations
    delegation   Functions for configuring delegation permissions
    group        Functions for group management
    keytab       Functions for keytab management
    machine      Functions for managing machine accounts
    ou           Functions for managing organizational units
    spn          Functions for service principal name (SPN) management
    user         Functions for user account management
    config       Functions for modifying adutil configuration
  Flags:
       --version       Displays the program version string.
    -h --help          Displays help with available flag, subcommand, and positional value parameters.
    -d --debug         Display additional debugging information when making LDAP/Kerberos calls.
       --accept-eula   Accepts the current EULA for adutil. This has no effect if the EULA has already been accepted.

You can run the following help options to seek help with the next level of commands:

$ adutil spn --help
spn - Functions for service principal name (SPN) management
  Usage:
    spn [add]
  Subcommands:
    add       Adds the provided SPNs to an account
    addauto   Automatically generate SPNs based on SPN component inputs and add them to an account
    delete    Deletes the provided SPNs from an account
    search    Search for an SPN by name or list all SPNs in the directory
    show      Get the list of SPNs assigned to an account
  Flags:
    --version       Displays the program version string.
    -h --help          Displays help with available flag, subcommand, and positional value parameters.
    -d --debug         Display additional debugging information when making LDAP/Kerberos calls.
       --accept-eula   Accepts the current EULA for adutil. This has no effect if the EULA has already been accepted.
$ adutil spn search --help
search - Search for an SPN by name or list all SPNs in the directory
  Usage:
     search [name]
  Positional Variables:
    name   OPTIONAL: Name of the SPN to search for in the directory. * can be used as a wildcard
  Flags:
    --version       Displays the program version string.
    -h --help          Displays help with available flag, subcommand, and positional value parameters.
    -n --name          OPTIONAL: Name of the SPN to search for in the directory. * can be used as a wildcard
    -f --filter        OPTIONAL: Filter for the search (User,Machine,Group)
    -o --ouname        OPTIONAL: Distinguished name of OU in which SPNs should be searched. If omitted, the entire directory will be searched.
    -d --debug         Display additional debugging information when making LDAP/Kerberos calls.
       --accept-eula   Accepts the current EULA for adutil. This has no effect if the EULA has already been accepted.

Running Ansible with adutil

Did you know that Ansible can automate your SQL Server deployment? The Ansible-based SQL Server collection uses adutil as a tool to enable AD authentication for SQL Server on Linux. Learn more about this in Automation Hub - microsoft.sql | Ansible Automation Platform (redhat.com) and Microsoft’s official documentation: Quickstart: Deploy SQL Server on Linux using an Ansible playbook - SQL Server

Further reading