|
| 1 | +--- |
| 2 | +title: Introduction to adutil - Active Directory Utility |
| 3 | +description: Overview of adutil and using it to configure Active Directory for SQL Server on Linux |
| 4 | +author: amvin87 |
| 5 | +ms.author: amitkh |
| 6 | +ms.reviewer: vanto |
| 7 | +ms.date: 09/30/2021 |
| 8 | +ms.topic: conceptual |
| 9 | +ms.prod: sql |
| 10 | +ms.technology: linux |
| 11 | +moniker: ">= sql-server-linux-2017 || >= sql-server-2017 || =sqlallproducts-allversions" |
| 12 | +--- |
| 13 | + |
| 14 | +# Introduction to adutil - Active Directory utility |
| 15 | + |
| 16 | +Adutil is a command-line interface (CLI) utility for interacting and managing Active Directory domains. You can use this tool to simplify Active Directory (AD) authentication configuration for both SQL Server on Linux and Linux-based SQL containers. Adutil eliminates the need to switch between Windows and Linux machines to manage Windows Active Directory when enabling AD authentication for SQL Server on Linux and containers. |
| 17 | + |
| 18 | +Having adutil isn't a prerequisite for enabling AD authentication for SQL Server on Linux. You can use utilities like ktpass, as explained in [Tutorial: Use Active Directory authentication with SQL Server on Linux](sql-server-linux-active-directory-authentication.md), to enable AD authentication for SQL Server on Linux or containers. |
| 19 | + |
| 20 | +Adutil is designed as a series of commands and subcommands, with additional flags that can be specified as further input. A category of administrative functions is represented by each top-level command. Within that category, each subcommand is an operation. We'll show you how you can download and get started with adutil. |
| 21 | + |
| 22 | +> [!NOTE] |
| 23 | +> adutil is a tool developed with SQL Server as the application. Hence, support for adutil will be limited for SQL Server use cases only. |
| 24 | +
|
| 25 | +## Installing adutil |
| 26 | + |
| 27 | +> [!NOTE] |
| 28 | +> If you do not accept the EULA during the time of install, when you run the adutil command for the first time, you will have to run it with the flag `--accept-eula`. This is true for all distributions. |
| 29 | +
|
| 30 | +# [RHEL](#tab/rhel) |
| 31 | + |
| 32 | +1. Download the Microsoft Red Hat repository configuration file. |
| 33 | + |
| 34 | + ```bash |
| 35 | + sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsoft.com/config/rhel/8/prod.repo |
| 36 | + ``` |
| 37 | + |
| 38 | +1. If you had a previous preview version of adutil installed, remove any older adutil packages using the below command. |
| 39 | + |
| 40 | + ```bash |
| 41 | + sudo yum remove adutil-preview |
| 42 | + ``` |
| 43 | + |
| 44 | +1. Run the following commands to install **adutil**. `ACCEPT_EULA=Y` accepts the EULA for adutil. The EULA is placed at the path `/usr/share/adutil/`. |
| 45 | + |
| 46 | + ```bash |
| 47 | + sudo ACCEPT_EULA=Y yum install -y adutil |
| 48 | + ``` |
| 49 | + |
| 50 | +# [Ubuntu](#tab/ubuntu) |
| 51 | + |
| 52 | +1. Import the public repository GPG keys and then register the Microsoft Ubuntu repository. |
| 53 | + |
| 54 | + ### Ubuntu 18.04 |
| 55 | + |
| 56 | + ```bash |
| 57 | + curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - |
| 58 | + sudo curl https://packages.microsoft.com/config/ubuntu/18.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list |
| 59 | + ``` |
| 60 | + |
| 61 | + ### Ubuntu 20.04 |
| 62 | + |
| 63 | + ```bash |
| 64 | + sudo wget -qO /etc/apt/trusted.gpg.d/microsoft.asc https://packages.microsoft.com/keys/microsoft.asc |
| 65 | + sudo curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list |
| 66 | + ``` |
| 67 | + |
| 68 | +1. If you had a previous preview version of adutil installed, remove any older adutil packages using the below command. |
| 69 | + |
| 70 | + ```bash |
| 71 | + sudo apt-get remove adutil-preview |
| 72 | + ``` |
| 73 | + |
| 74 | +1. Run the following command to install **adutil**. `ACCEPT_EULA=Y` accepts the EULA for adutil. The EULA is placed at the path `/usr/share/adutil/`. |
| 75 | + |
| 76 | + ```bash |
| 77 | + sudo apt-get update |
| 78 | + sudo ACCEPT_EULA=Y apt-get install -y adutil |
| 79 | + ``` |
| 80 | + |
| 81 | +# [SLES](#tab/sles) |
| 82 | + |
| 83 | +1. Add the Microsoft SQL Server repository to Zypper. |
| 84 | + |
| 85 | + ### SLES 12 |
| 86 | + |
| 87 | + ```bash |
| 88 | + sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc |
| 89 | + sudo zypper addrepo -fc https://packages.microsoft.com/config/sles/12/prod.repo |
| 90 | + ``` |
| 91 | + |
| 92 | + ### SLES 15 |
| 93 | + |
| 94 | + ```bash |
| 95 | + sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc |
| 96 | + sudo zypper addrepo -fc https://packages.microsoft.com/config/sles/15/prod.repo |
| 97 | + ``` |
| 98 | + |
| 99 | +1. If you had a previous preview version of adutil installed, remove any older adutil packages using the below command. |
| 100 | + |
| 101 | + ```bash |
| 102 | + sudo zypper remove adutil-preview |
| 103 | + ``` |
| 104 | + |
| 105 | +1. Run the following command to install **adutil**. `ACCEPT_EULA=Y` accepts the EULA for adutil. The EULA is placed at the path `/usr/share/adutil/`. |
| 106 | + |
| 107 | + ```bash |
| 108 | + sudo ACCEPT_EULA=Y zypper install -y adutil |
| 109 | + ``` |
| 110 | + |
| 111 | +--- |
| 112 | + |
| 113 | +## Manage Windows AD using adutil |
| 114 | + |
| 115 | +Ensure that you download adutil to a host that is domain joined. You also need to obtain or renew the kerberos TGT (ticket-granting ticket) using the `kinit` command. Ensure that the account you use to `kinit` with has the permissions to execute the actions you intend to run on Windows AD through the adutil tool. For example, if you intend to create accounts and service principal names (SPN) using the adutil tool, then you should `kinit` with the account that has privileges to create SPNs and users on your AD. |
| 116 | + |
| 117 | +Here are some examples of actions that you can perform using adutil. To see a list of top-level commands, type `adutil --help`. This command will show you the top-level commands that you can use to manage and interact with AD. |
| 118 | + |
| 119 | +```bash |
| 120 | + $adutil --help |
| 121 | + adutil - A general AD utility |
| 122 | + Usage: |
| 123 | + adutil [account|delegation|group|keytab|machine|ou|spn|user|config] |
| 124 | + Subcommands: |
| 125 | + account Functions for generic account operations |
| 126 | + delegation Functions for configuring delegation permissions |
| 127 | + group Functions for group management |
| 128 | + keytab Functions for keytab management |
| 129 | + machine Functions for managing machine accounts |
| 130 | + ou Functions for managing organizational units |
| 131 | + spn Functions for service principal name (SPN) management |
| 132 | + user Functions for user account management |
| 133 | + config Functions for modifying adutil configuration |
| 134 | + Flags: |
| 135 | + --version Displays the program version string. |
| 136 | + -h --help Displays help with available flag, subcommand, and positional value parameters. |
| 137 | + -d --debug Display additional debugging information when making LDAP/Kerberos calls. |
| 138 | + --accept-eula Accepts the current EULA for adutil. This has no effect if the EULA has already been accepted. |
| 139 | +``` |
| 140 | +To seek help with the next level of commands, you can further run the help option as shown below: |
| 141 | +
|
| 142 | +```bash |
| 143 | +$ adutil spn --help |
| 144 | +spn - Functions for service principal name (SPN) management |
| 145 | + Usage: |
| 146 | + spn [add|addauto|delete|search|show] |
| 147 | + Subcommands: |
| 148 | + add Adds the provided SPNs to an account |
| 149 | + addauto Automatically generate SPNs based on SPN component inputs and add them to an account |
| 150 | + delete Deletes the provided SPNs from an account |
| 151 | + search Search for an SPN by name or list all SPNs in the directory |
| 152 | + show Get the list of SPNs assigned to an account |
| 153 | + Flags: |
| 154 | + --version Displays the program version string. |
| 155 | + -h --help Displays help with available flag, subcommand, and positional value parameters. |
| 156 | + -d --debug Display additional debugging information when making LDAP/Kerberos calls. |
| 157 | + --accept-eula Accepts the current EULA for adutil. This has no effect if the EULA has already been accepted. |
| 158 | +``` |
| 159 | +
|
| 160 | +```bash |
| 161 | +$ adutil spn search --help |
| 162 | +search - Search for an SPN by name or list all SPNs in the directory |
| 163 | + Usage: |
| 164 | + search [name] |
| 165 | + Positional Variables: |
| 166 | + name OPTIONAL: Name of the SPN to search for in the directory. * can be used as a wildcard |
| 167 | + Flags: |
| 168 | + --version Displays the program version string. |
| 169 | + -h --help Displays help with available flag, subcommand, and positional value parameters. |
| 170 | + -n --name OPTIONAL: Name of the SPN to search for in the directory. * can be used as a wildcard |
| 171 | + -f --filter OPTIONAL: Filter for the search (User,Machine,Group) |
| 172 | + -o --ouname OPTIONAL: Distinguished name of OU in which SPNs should be searched. If omitted, the entire directory will be searched. |
| 173 | + -d --debug Display additional debugging information when making LDAP/Kerberos calls. |
| 174 | + --accept-eula Accepts the current EULA for adutil. This has no effect if the EULA has already been accepted. |
| 175 | +``` |
| 176 | +
|
| 177 | +## Samples |
| 178 | +
|
| 179 | +Each command is documented so that you can get started right away. Here are some of the typical activities that adutil is used for when configuring or administering AD authentication for SQL Server on Linux and containers: |
| 180 | +
|
| 181 | +- Creating an account in AD: |
| 182 | +
|
| 183 | + ```bash |
| 184 | + adutil user create --name sqluser --distname CN=sqluser,CN=Users,DC=CONTOSO,DC=COM |
| 185 | + ``` |
| 186 | +
|
| 187 | +- Creating SPNs associated with an account or service: |
| 188 | +
|
| 189 | + ```bash |
| 190 | + adutil spn addauto -n sqluser -s MSSQLSvc -H mymachine.contoso.com -p 1433 |
| 191 | + ``` |
| 192 | +
|
| 193 | +- Creating keytabs using adutil: |
| 194 | +
|
| 195 | + ```bash |
| 196 | + adutil keytab createauto -k /var/opt/mssql/secrets/mssql.keytab -p 1433 -H mymachine.contoso.com --password 'P@ssw0rd' -s MSSQLSvc |
| 197 | + ``` |
| 198 | +
|
| 199 | +You can refer to the reference manual page of adutil using the command `man adutil`. |
| 200 | +
|
| 201 | +## Next steps |
| 202 | +
|
| 203 | +- [Configure Active Directory authentication with SQL Server on Linux using adutil](sql-server-linux-ad-auth-adutil-tutorial.md) |
| 204 | +- [Configure Active Directory authentication with SQL Server on Linux containers](sql-server-linux-containers-ad-auth-adutil-tutorial.md) |
| 205 | +- [Rotate SQL Server on Linux keytabs](sql-server-linux-ad-auth-rotate-keytabs.md) |
0 commit comments