The directadmin binary

The directadmin binary file is responsible for running the DirectAdmin panel itself, but also has a variety of uses. You can find the binary here in /usr/local/directadmin/directadmin.

During installation a command alias is also installed it is a symlink from /usr/local/bin/da to /usr/local/directadmin/directadmin. This allows using a short command da to execute it without specifying a full path and name of the binary.

If calling DirectAdmin binary with da command does not work please make sure /usr/local/bin is included on your shell PATH environment variable (is is included by default on most of the systems). Call to da can be always substituted with call to /usr/local/directadmin/directadmin and vice versa. For the brevity we will be using da alias in the rest of this document.

A common way of starting the panel is via the following command:

service directadmin start

But you can call the directadmin daemon right from the binary with

da server --daemonize

To get the DirectAdmin version, use:

da version

Another common use is to set directadmin.conf values, for example:

da config-set letsencrypt 1 --restart

The last --restart key means that dataskq should restart the DirectAdmin panel when dataskq is launched next (dataskq is ran every minute).

You can run directadmin in debug mode (should be stopped before):

da server --debug=2000

Where 2000 is a verbosity level of debug information to print.


General help of the binary itself

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

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

Available commands:
  admin             Print admin username
  admin-backup      Perform admin-level backups
  api-url           Create a login-key for HTTP API access (aliases: root-auth-url)
  config            Print Directadmin config
  config-set        Set Directadmin config value
  database-create   Create SQLite database
  doveadm-quota     Print email usage quota
  info              Print binary compile info
  install           Run Directadmin installer
  license           Print license info
  login-url         Create single-sign-on URL (aliases: create-login-url)
  permissions       Set Directadmin files permissions
  server            Run Directadmin web server
  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

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)

To show the license information:

da license

How to create a one-time login hash

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 something similar to:

URL: http://1.2.3.4:2222/CMD_LOGIN_URL?hash=cJbIk9GNsXk43....xmAHSTaKFiFe

where the hash value is a randomly long length from 120 to 148 characters.

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).

Technical details regarding login-url

  1. 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.

  1. 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.

Duration of login-url generated login hashes

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

Restrictions regarding login-url

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.

  1. 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
  1. 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.

Last Updated: