Directadmin Docs

Authentication Hooks

session_create_pre.sh

The session_create_pre.sh hook is executed after successful login operation, but before a new session is created and user allowed to access DirectAdmin GUI. It gives an opportunity for hook scripts to abort user login operation.

Accessing DirectAdmin via API DOES NOT create a session, and this hook will not be called.

This script can be handy if you'd like to notify yourself of a session-based login, but you won't be notified for any API based actions for the same account (this won't be called for API calls).

Be sure to exit with a zero-status. If you exit with a non-zero status, the write of the session file will be aborted, and the login won't work.

All non-zero exit statuses will be logged to the /var/log/directadmin/error.log, but the login page will just refresh with no errors.

Environment variables

  • username: username
  • password : password
  • session_id : generated session ID
  • ip : ip of the user
  • referer : Referer header passed to DA in the request
  • user_agent : User-Agent header passed to DA in the request

session_destroy_pre.sh

If a session is to be destroyed due to old age, or due to logout, session_destroy_pre.sh will be called just before the session file at /usr/local/directadmin/data/sessions/sess_XXX is removed.

Environment variables for a standard login

  • username: username
  • passwd: base64 encrypted password
  • key: secret key used for session
  • host: host
  • ip: ip of the user
  • file: path to the session file to be removed
  • home_memory:

Environmental values passed will be the entire contents of the session file, plus:

file=/usr/local/directadmin/data/sessions/sess_XXX  #path to the current session file.

Contents of a session file might look like this, but can vary:

home_memory=3
host=2.3.4.5
ip=1.2.3.4
key=SEbYTmsYQ7kccy0OhWenhidoEs6POWfqiEO2yHgPMQzyOxM3TAp9rfv5V2UtW7hE
login_key=keyname
passwd=base64encodedpasswd
selected_domain=domain.com
username=admin

If a Login Key is used to login to DA, the login_key=keyname is added to the session file. You can then get info on that login key with this path:

/usr/local/directadmin/data/users/$username/login_keys/${login_key}/*

Note that this does not account for the "login-as" method, which might set the username to be:

username=admin|fred

So be sure to check for that in the $username variable before using it, e.g.,

REALUSER=`echo "$username" | cut -d\| -f1

In the above example, the login_key and key pass would be from User "admin" and not "fred". Use $REALUSER throughout your script instead of $username if the "login-as" method is used.

Unlike other pre.sh scripts, the exit code of your script will not abort the deletion process, as we should never block the removal of a session. It is highly recommended that you use exit 0; at the end of your script, in case this policy does change later on.

login_key_(create|modify)_post.sh

This hook will be triggered when a Login Key is either being created or modified, or if a One-Time Login Hash URL is being created (as it essentially creates a special login key to do this).

Environment variables

  • keyname:name of the login key
  • is_login_url (0|1): if 1, we're creating the one-time login hash url. 0 means a normal login key.
  • modifying (0|1): whether this is a new login key or modifications to an existing login key
  • key: secret key. only applies to creations, it's the plaintext/raw password for the key to work with.
  • expiry_timestamp: unix timestamp for the current expiry of the key. 0 means never.
  • max_uses: how many times the key could be used. 0 means unlimited.
  • allow: list of CMDs allowed, separated by | character
  • deny: list of CMDs denied, separated by | character
  • ips: list of IPs allowed, separated by | character.
  • login_keys_notify_on_creation (0|1|2): based on the directadmin.conf setting, altered by DA at run-time, determines whether a notice should be sent for this call.

Environment variables

  • username : username
  • password : password
  • session_id : session ID generated
  • ip : ip of the user
  • referer : Referer header passed to DA in the request
  • user_agent : User-Agent header passed to DA in the request

lost_password_pre.sh

The hook script, /usr/local/directadmin/scripts/custom/lost_password_pre.sh, will run before all calls of the CMD_LOST_PASSWORD command. If you exit with a non-zero value, the script will abort the process.

Environment variables

  • username : username
  • password : password
  • session_id : session ID generated
  • ip : ip of the user
  • referer : Referer header passed to DA in the request
  • user_agent : User-Agent header passed to DA in the request

one_click_pma_login_post.sh

New optional hook to use with the phpMyAdmin one-click login feature:

one_click_pma_login=1

The exit code should be 0 for success and 1 for error, however error or not, the behavior will not be altered and the output will not be modified.

The only variance is a debug output at level 100 will provide info from your script.

This is basically just a silent script to take action as needed.

Environment variables

  • token: token name
  • username: pma login name (will be formatted similar to 'da_sso_XXXXXXXXX')
  • passwd: secret pass, known to no-one, except internally in DA, set in DB User account.
  • name: Database User name.

Note: name may be set to username_%% in the event that all User databases are to be accessible for this token.

login_pre.sh (Deprecated)

Note: Usage of this hook is discouraged, it will only work for old command based requests.

The hook login_pre.sh is an extra layer of security, should you wish to use it. A strong password is good, but a strong password from an approved IP is better.

Integrated right into the user/pass authentication code, this script allows the server admin to check the remote ip, user, password, and referer of the connection.

If the script exists, it will be called for all requests, since authentication is done for each request (even with sessions).

The script enables the server admin to allow or deny a request based on any criteria they wish.

Any non-zero exit code here will count against the brute-force check, even if the correct password is passed.

A non-zero exit code will add an entry into your error.log with any text you echo.

Last Updated: