User API commands

User API

The following documentation is officially supported by DreamHost. However, if you find any instructions in this article do not function as intended, it's possible it may be out of date. When in doubt, please contact support for further assistance.

The user API module manages Shell and FTP users

The user-list_users command also lists mail users.

Commands

user-add_user

Adds a user (of type ftp, sftp, or shell). If you do not specify a password, a password is randomly generated and displayed in the result. Otherwise the result displays ******** for the password. A Service token is also returned (see Service Control Commands).

Command user-add_user
Values

type : The type of user; can be ftp, sftp, or shell
username : The desired username for the new user
gecos : The Full Name for this user, like John Smith (this field cannot be blank)
server : The home for the user (the shared server or VPS). This is required
shell_type : The type of shell for the user (bash, tcsh, ksh, or zsh). Only required if the type is shell
password : (optional) The password for the new user. Randomly generated if not specified
enhanced_security : (optional) Set to 1 to enable Enhanced User Security (set to 0 or leave blank to disable)

Result

success
username password token
testuser123 ******** gcnaBcD12eFgH34iJkL

Possible errors

no_type
no_username
no_gecos
no_server
no_shell_type
invalid_type
invalid_shell_type
invalid_server
invalid_username (specific error after a tab)
user_exists
invalid_gecos (specific error after a tab)
invalid_password (specific error after a tab)

user-list_users

Dump a list of all users (including ftp, shell, anonymous ftp, backup, and mailboxes) on all accounts you have access to. Passwords are no longer available via this API command.

Command user-list_users
Values

(none)

Result

success
account_id username type shell home password disk_used_mb quota_mb gecos
1 anftp ftp /etc/ftponly machine.dreamhost.com 0 671744 An FTP user
1 b1 backup /usr/bin/rssh backup.dreamhost.com 0 671744 Account #1 Backup User
1 blah shell /bin/bash machine.dreamhost.com 0 671744 Blah Shell
1 josh@blah.com mail /etc/poponly smaug.dreamhost.com 0 671744 Josh Email User!

Possible values

type : typically ftp, sftp, shell, mail, or backup

Possible errors

(none)

user-remove_user

Removes a user specified by the username. Optionally the type of user or home can be specified to distinguish the user to delete (if the user exists on multiple homes/types). To specify the home, set the username to username@home. If the username has more than one type/home, you can set remove_all to remove all instances of the user (note: if remove_all is set and the type or home is specified, it removes all instances of username with that type or on that home).

Command user-remove_user
Values

username : the user to remove, like testuser42. Optionally use username@home to specify a home, like testuser42@riga
type : (Optional) the type of user, like ftp, shell, etc
remove_all : (Optional) set to 1 to remove all instances of this user (if user has multiple types or is on multiple homes)

Result

success

Possible errors

invalid_user (specific error after tab)
multiple_user_services (specific error after tab, such as the user has more than one type/home and the type/home and remove_all were not set)
cannot_remove_user (specific error after tab)

See also

 

Did this article answer your questions?

Article last updated .