The directadmin binary

The directadmin binary file is the main application that runs DirectAdmin web interface, but it also contains a lot of sub-comands for additional functionality. Default installation location for binary file is /usr/local/directadmin/directadmin.

As part for DirectAdmin installation procedure a symlink from /usr/bin/da to /usr/local/directadmin/directadmin is created. This makes main binary file accessible as da command without having to specify full path.

Call to da can be always substituted with call to /usr/local/directadmin/directadmin and vice versa. For the brevity the alias command da is used in the documentation.

Commonly used da commands:

da login-url - get one time URL to log-into the web interface with main Administrator account.
da version - print DirectAdmin version information.
da config - dump all configuration parameter that can be used set in directadmin.conf.
da config-set {key} {val} --restart - change single configuration parameter and restart DirectAdmin service.
da admin - show the name of main Administrator account.
da license - show DirectAdmin license information.
da update - update DirectAdmin to the latest version.

Web service

A standard way to start DirectAdmin web service is using systemd, with command:

systemctl start directadmin

Web service can be started manually from the shell with:

systemctl stop directadmin
da server

Care should be taken to make sure only one web service is running on the system, trying to run two instances will fail because listening port is already in use. Running web service from the terminal should not be used in production as web service will get stopped when the terminal is closed.

To get more verbose information on what web service is doing it can be in debug mode, by passing additional --debug={level} parameter. Where {level} is debug verbosity level (higher level - more verbose output). Example:

systemctl stop directadmin
da server --debug=2000

General help of the binary itself

List of all available da sub-commands can be printed using --help flag:

# da --help
Usage:
  directadmin [OPTIONS] <command>

Help Options:
  -h, --help  Show this help message

Available commands:
  admin             Print admin username (aliases: a)
  admin-backup      Perform admin-level backups
  api-url           Create a login-key for HTTP API access (aliases: root-auth-url)
  build             Run CustomBuild script, manage 3rd party software
  config            Print DirectAdmin config (aliases: c)
  config-get        Get DirectAdmin config value
  config-set        Set DirectAdmin config value
  doveadm-quota     Print email usage quota
  info              Print binary compile info (aliases: o)
  install           Run DirectAdmin installer
  license           Print license info (aliases: l)
  license-set       Change license key
  login-url         Create single-sign-on URL (aliases: create-login-url)
  permissions       Set DirectAdmin files permissions (aliases: p)
  server            Run DirectAdmin web server (aliases: d, s)
  suspend-domain    Suspend domain
  suspend-user      Suspend user
  taskq             Run dataskq
  unsuspend-domain  Unsuspend domain
  unsuspend-user    Unsuspend user
  update            Update DirectAdmin
  version           Print DirectAdmin version (aliases: v)

However, aside from generic options shown with the help (--help) above, each command has it's own unique set of options, available to see, e.g.:

# da api-url --help
Usage:
  directadmin [OPTIONS] api-url [api-url-OPTIONS]

Help Options:
  -h, --help      Show this help message

[api-url command options]
          --user= User (default: admin)

You can now create a one-time use URL which will automatically log you in as the specified User.

Note: If Login Keys are not enabled for the given User in their user.conf, they will be enabled when this script is ran. If the given "--user=" account does not have login_keys enabled, any time a login-url is run for this User, login_keys=ON will automatically be set.

A system.log entry will be added if login keys had to be enabled for the user, such as the following for the admin user:

"Authentication::create_one_time_hash: set login_key=ON for admin for login hash."

To send someone a login URL to be logged in as admin, type:

da login-url --user=admin

which will output URL that when opened in the browser performs automatic log-in:

URL: http://server.example.com:2222/api/login/url?key=VGhpcyBpcyBub3QgYSByZWFsIGtleSEh

You can even choose the URL path where you'd like the user redirected upon login:

--redirect-url=/CMD_PATH?to=whatever

For example, if you need an immediate redirect to a specific plugin within the hash, your creation call might be like:

da login-url --user=admin --redirect-url=/CMD_PLUGINS_ADMIN/hello_world/index.html

which will generate a hash URL, as usual, except when you navigate to this URL, after it's accepted, you'll be redirected to this above path.

This must be a GET request, since you cannot redirect into a POST (what you do on something.html is up to you).

The hash is stored on disk the global file /usr/local/directadmin/data/admin/login_hashes.conf, but it will be crypted as the "left-side" index, with details about this hash on the right-side.

Thus, a lookup of a given hash must cycle through each item, testing the crypt until found.

It does create a Login Key under this User, but instead of a crypted key, it saved "key=hash", signifying that it's a login URL, standing by.

Once a valid hash has been accepted, the login key is swapped with a true crypted password, and that password is set in the sessions file. The password for this key is never seen. The original login hash is removed from the global login_hashes file. Cookie is sent, and the login works just like any other Login Key.

By Default the Login Hashes live for 3 days, including the end of the Login Key time. So you have up to 3 days to login and logout. (It's not extended upon hash-to-key conversion).

You can set a different time, for example, to one day, by adding the following to the login-url options list:

--expiry=1d

Valid time units are: s,m,h,d,w,M,y and ARE case sensitive.

The option also exists to allow one to alter the internal default time:

login_hash_expiry_minutes=4320

With the above example of 4320, it remains set the same as the internal default as it was before this option was added, which is 3 days.

Even after setting a new default value, you can still specify a different expiry during creation, e.g.:

./directadmin login-url --user=fred --expiry=1d

IPs: You can list one or many IPs or 1.2.3.4-7 ranges by adding this to the options: --ip=1.2.3.4 --ip=5.6.7.8-9

Getting API/GUI access for any user account from CLI

If you have a script/tool that needs to use DA on behalf of main admin user or any other user account, you can automatically generate short lived login-key.

This key can be passed to curl/API, generated on the fly if needed.

Generating API access URL for main admin account:

da api-url

This command will print out URL with login-key credentials, example

https://admin:YNcB-eqgVTHtewC_d_WCNLC9hgnHd0BE@server.example.net:2222

Generating API access URL for other accounts:

da api-url --user=foo

Would print out:

https://user:my2VzpqtJBPZKRS62EPpXU1hs4DTZ4Dq@server.example.net:2222

Generated API URL can be used directly in the curl call, example:

curl -k "$(da api-url)/CMD_API_SHOW_ALL_USERS?json=yes"

The generated key will be temporary thus the CLI call to get URL should be executed before each API usage and not cached.

Same login-keys can be used to access web GUI as well.

Get the main Admin username

Many scripts require the top-level admin account name. This is not always going to be "admin", so a new command is available to output the admin username:

da admin

which would output nothing more than the following if the admin username is 'admin':

admin

Managing suspensions

These directadmin command line options let you suspend/unsuspend accounts from ssh as rootopen in new window:

Suspend account (any account type):
da suspend-user --user=fred
Unsuspend account:
da unsuspend-user --user=fred
Suspend domain:
da suspend-domain --domain=domain.com
Unsuspend domain:
da unsuspend-domain --domain=domain.com
You can also include: --reason=Xopen in new window where X must be one of the reason indexes (left side) in the file:
/usr/local/directadmin/data/templates/suspension_reason.txt
Omitting a reason will set the reason to be "root ssh" as it was before.
Contents of the file /usr/local/directadmin/data/templates/suspension_reason.txt include:

user_bandwidth=id=12&text=User Bandwidth
user_quota=id=13&text=User Disk Quota
domain_bandwidth=id=14&text=Domain Bandwidth
domain_quota=id=15&text=Domain Quota
reseller_bandwidth=id=16&text=Reseller Bandwidth
reseller_quota=id=17&text=Reseller Quota
billing=id=18&text=Billing Issue
abuse=id=19&text=Abuse
spam=id=20&text=Spam
other=id=21&text=Other
inactive=id=23&text=Inactive

So, a valid command would be:
da suspend-user --user=fred --reason=other

NOTE: The suspension_reason.txt now only used from internal list for translation purposesopen in new window, though it can still be copied to the custom/ directory for customizing the suspension reasons as described below.

Customizing the suspension reason

You may customize the supension reasonopen in new window by customizing the DirectAdmin template file suspension_reason.txt. Copy the file to the /usr/local/directadmin/data/templates/custom directory and edit this custom copy in order to add, edit, or remove the reasons for suspensions as desired.

The id values for the key names are internal language pack id numbers set in:
/usr/local/directadmin/data/skins/enhanced/lang/en/internal/suspension.txt

Note, if you just want to set the text, and not make your entries translatable, then simply don't include an id value.

A sample reason without an id:
smelly=text=He Really Smells Bad

Both cases must have a "text" variable, as it will be the fallback in the event that the id cannot be found in the given language file.

Show DocumentRoots

You can show all documentroots set in your system using the directadmin binaryopen in new window.

This is an option for CMD_DOMAIN or CMD_API_DOMAIN, both of which will only output JSON:

CMD_DOMAIN?action=document_root

Where all domains' documentroots will be output.

This can be used via the directadmin binary like so:

da docs-root

Sample output:

{
	"users":
	{
		"fred":
		{
			"domains":
			{
				"test.com":
				{
					"private_html": "/home/admin/domains/test.com/private_html",
					"public_html": "/home/admin/domains/test.com/public_html",
					"subdomains":
					{
						"forum":
						{
							"private_html": "/home/admin/domains/test.com/private_html/forum",
							"public_html": "/home/admin/domains/test.com/public_html/forum"
						}
					}
				},
				"domain.com":
				{
					"private_html": "/home/admin/domains/domain.com/private_html",
					"public_html": "/home/admin/domains/domain.com/public_html",
					"subdomains":
					{
						"sub":
						{
							"private_html": "/home/admin/domains/domain.com/private_html/sub/sub",
							"public_html": "/home/admin/domains/domain.com/public_html/sub/sub"
						}
					}
				}
			}
		}
	}
}

This command can be called by users when directadmin is running in suid mode to show the docroot for the user's domains, or it can be called by root when not running in suid mode, which will show the docroot for all users.

The call to da docs-root figures out the DocumentRoot values for both http and https, for each domain, subdomain, and pointer. These values are very dynamic and can be altered by various different areas, so the only way to know the true value is to fully compute it. Doing this on the fly for all VirtualHosts on the box can take several seconds (in the scenario triggering this change, it took 18s).

To speed things up, we'll create a new file:
/usr/local/directadmin/data/users/fred/DocumentRoot.cache.json
This file is created if the file does not exist, or the cache.json file is older than the current httpd.conf, nginx.conf, or openlightspeed.conf, depending on your active webserver. If the cache is newer than the httpd.conf, this cache is used for the docs-root call, greatly speeding it up. If the cache is not there, or older, then it's computed normally with the docs-root call, but written just as the output is generated by the call, ready for next time.

Get dovecot quotas

This is used for per-User calls.

Usage example:

./directadmin doveadm-quota --email=user@domain.com

which can be called as root, mail or a User.

If called as a User, it will ensure that domain.com belongs to the UID caller (not likely a common usage, but is an option since suid was needed anyway for 'mail').

If root or mail, it will work for any email that exists in the system.

If the email is valid and dovecot quotas work, then it will output something like:
18237:102400
which would be in KB. So, in the above example, the account is using about 20Meg of 100Meg.

You MUST check the exit code of the directadmin call.
If it's not 0, then ignore this directadmin result.

If the account in question has unlimited dovecot quotas, then the output will be:
0:0

This feature uses the doveadm quota call to get the info, as dovecot is going to be what will accept/reject the email anyway.

The purpose of this feature is to allow exim the ability to block an inbound email at smtp-time via ACL, rather than accepting the message and having it bounce after the dovecot lmtp delivery rejects it.

The ACL in question does not yet exist. If it will exist, it wouldn't be for a while after this version of DirectAdmin has been released.

# The directadmin binary

# Web service

# General help of the binary itself

# How to create a one-time login hash

# Technical details regarding login-url

# Duration of login-url generated login hashes

# Restrictions regarding login-url

# Getting API/GUI access for any user account from CLI

# Get the main Admin username

# Managing suspensions

# Customizing the suspension reason

# Show DocumentRoots

# Get dovecot quotas

The directadmin binary

Web service

General help of the binary itself

How to create a one-time login hash

Technical details regarding login-url