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 indirectadmin.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)
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 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).
Technical details regarding login-url
- 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.
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.
- 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 root:
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=X
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 purposes, 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 reason 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 binary.
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.