man(1)

NAME
privacyideaadm - manage the privacyIDEA server and OTP tokens.

SYNOPSIS
privacyideaadm --url=<privacyideaserver> [ --admin=<adminuser> ] --command=<commands> [ command options ]

DESCRIPTION
privacyideaadm.py is the command line client to manage the privacyIDEA server. The privacyIDEA server is a authentication backend, that can handle many different OTP (one time password) tokens.

COMMON OPTIONS

--url=<server>
-U <server>
    With this parameter you specify on which URL you want to contact the privacyIDEA server. This parameter is mandatory. The privacyIDEA server will usually run on port 80 or 443, if you are using SSL. Or - if the privacyIDEA server is simply run by paster - it also may run on 5000 or 5001. So the right url should be --url=https://privacyideaserver:443 or --url=http://privacyideaserver:80.

--admin=<adminuser>
-a <adminuser>
    If you need to authenticate to the admin interface, you can specify the name of the admin user here. You will be asked for the password.

--cert=<file>
-c <file>
    If the server is configured to request a client certificate to authenticate to the admin interface, you can specifiy the name of the PKCS#12 file here. If the private key of the PKCS#12 file is passphrase protected, you will be asked for the passphrase.

--key=<file>
-k <file>
    If you are using a client certificate for the admin interface, you may specify the name of the key file here.

--version
-v
    Print version information of this privacyideaadm management client.

--help
-h
    Print help information on the parameters and options.

--automate=<config file>
    The parameters are read from the config file. Can be combined with parameters on the command line. For a config file example see below.

--command=<command>
-C <command>
    Specify which command you want to execute on the privacyIDEA server. A list of all commands can be found in the section COMMANDS.

TOKEN MANAGEMENT COMMANDS
The privacyIDEA server accepts many different commands that can be sent to the server using this management client. Each command can take several arguments. These are described in more detail in the section COMMAND ARGUMENTS. You may issue the following commands. The arguments the command will accepts are listed behind the command. Optional parameters are denoted in square brackets.

listtoken [ --user= | --serial= ]
    This command returns a list of the token known by the privacyIDEA server. The list can be filtered for users or serialnumber of the token. The user needs to be entered as loginname.

listuser
    This lists the users the privacyIDEA server will find in all confgiured UserIdResolvers.

inittoken --serial= --otpey= [--user=] [--description=] [--pin=] [--etng] [--pytoken] [--type=]
    This command initializes a token, i.e. it creates a new token in the database. The only mandatory parameters are --serial and --otpkey. If you like to, you can also issue the parameter --user. In this case the token will be assigned immediately to this user. Als you can set the PIN, add a description or specify the tokentype.

assigntoken --user= --serial=
    This will assign the token with the given serial number to the given user.

unassigntoken --serial=
    This will unassign the token with the given serial number from its user.

importtoken --file= | -f
    This will import tokens that are defined in an XML file to the privacyIDEA server. The file needs to be in the format for eToken PASS by SafeNet/Aladdin.

disabletoken --serial= | --user
    This will disable the token with the given serialnumber or all tokens of the given user. Disabling a token means, that it can not be used to authenticate anymore, as long as it is not enabled again.

enabletoken --serial= | --user=
    This will enable a disabled token again.

removetoken --serial= | --user=
    This will remove the token with the given serialnumber or all tokens of the given user from the privacyIDEA server.

resynctoken --serial= | --user= --otp1= --otp2=
    This will resync an evenbased token like the HMAC OTP tokens. You need to specify the serialnumber and also two succeeding OTP values.

set --user= | --serial= [--pin=] [--maxfailcount=] [--syncwindow=] [--otplen=]
    This can set several values for one token or all tokens of the given user.

SECURITY MODULE COMMANDS
A security module is a module to be used to store the encrpytion keys and encrypt and decrypt data. In the privacyidea.ini file you need to configure the security module, which can be a file, a PKCS11 smartcard or hardware security module. Some security modules need a password to access the encryption keys. You can either specify the password in privacyidea.ini or you can enter the password afterwards using this command. securityModule
    This will retrieve the information about the current security module. To set the password for the security module, you need to specify the module name with the parameter --module.
securityModule --module=<modulename>
    Set the password for the module defined in privacyidea.ini.

SERVER CONFIGURATION COMMANDS

getconfig
    This returns the complete server configuration of the privacyIDEA server as it is stored in the Config table of the token database.

setconfig --config=
    This can be used to set a single config value like --config='DefaultSyncWindow=512'.

REALM AND RESOLVER CONFIGURATION COMMANDS
A privacyIDEA server may have several UserIdResolvers configured. A UserIdResolver tells the privacyIDEA server, where the users are stored. This can be flat files on the privacyIDEA server, SQL servers or LDAP/AD servers. Several UserIdResolvers can be grouped togeather into a "REALM". Thus one privacyIDEA server can manage several user with the same loginname, as long as they reside in different realms. A user needs to provide the realm he belongs to. Either he needs to do this directly or the authentication module might be configured this way, to add the realm. If the user does not provide and realm and the authentication modul also does not set any realm, this user is looked up in the DEFAULT REALM. These commands can be used to configure UserIdResolvers and realms.

getrealms
    This lists all realms. Within each realm you can see, which UserIdResolvers belong to this realm. This command takes no parameter.

setrealm --realm=<realmname> --resolver=<resolverlist>
    This command will set the resolverlist of a realm. If the realm does not exist, it will be created. If the realm does exist, the old resolverlist will be overwritten.

deleterealm --realm=<realmname>
    This will delete the realm with the given name. The UserIdResolvers will not be deleted.

setdefaultrealm --realm=<realmname>
    This will set the default realm.

getresolvers
    This returns a list of all UserIdResolvers. This command takes no arguments.

deleteresolver --resolver=<resolvername>
    This will delete the UserIdResolver with the given resolvername.

setresolver --resolver=<resolvername> --rtype=[LDAP|SQL|FILE] ...
    This will create a new UserIdResolver or reconfigure a given UserIdResolver. The type of the UserIdResolver is set with the parameter --rtype. A detailed list of parameters for setting up UserIdResolvers can be found in seciont USERIDRESOLVER PARAMETERS.

COMMAND ARGUMENTS

--user=<user>
    This argument is always used, when token operations are run on a user. This expects the loginname of the user.

--pin=<pin>
    This expects the OTP PIN, when setting the OTP PIN for a given token.

--serial=<S/N>
    Token are always addressed by their serial number. So always when you are doing some operation on a token, you need to specify the serial number.

--description=<description of token>
    Each token may have a desription. You can use this argument to set it.

--otpkey=<BASE64>
    This is the HMAC secret that is used to calculate the OTP values. In case of MOTP token, this is the motp secret.

--file=<file>
    Used to specify the XML filename with the token definitions to import.

--otp1=, --otp2=
    The succeeding otp values when resyncing an event based token.

--window=<window size>
    This is the resync windows size, when resyncing tokens.

--etng
    When doing an inittoken, this flag tells the client to initialize an eToken NG OTP.

--pytoken
    When doing an inittoken, this flag tells the client that a pytoken should be generated.

--type=<tokentype>
    When doing an inittoken, this arguemnts tells, what kind of token should be initialized. Valid values: "HMAC" (default), "motp".

--realm=<realmname>
    When dealing with realms, this takes the name of the realm. It should only contain the characters a-z,0-9 and the "minus".

--resolver=<resolvername> or --resolver=<resolverlist>
    With some commands this arguemnt takes a single resolvername, with others a comma seperated list of resolver identifiers.

--csv
    This parameter adds to the command "listtoken". Show the token list as CSV format.

--export_fields=<additional user fields>
    Additional fields from the useridresolver to add to the export.

USERIDRESOLVEER PARAMETERS

--rf_file
    Resolver FILE: the filename containing the users on the privacyIDEA server

--rl_uri
    Resolver LDAP: the LDAP uri of the ldap server

--rl_basedn
    Resolver LDAP: the BaseDN for searching for users

--rl_binddn
    Resolver LDAP: the BindDN to authenticate to the LDAP server

--rl_bindpw
    Resolver LDAP: the Bind Password to authenticate to the LDAP server

--rl_timeout
    Resolver LDAP: the timeout when connecting to the LDAP server

--rl_loginattr
    Resolver LDAP: the attribute containing the loginname like uid

--rl_searchfilter
    Resolver LDAP: the searchfilter. Something like (uid=*)(objectClass=inetOrgPerson)

--rl_userfilter
    Resolver LDAP: the userfilter for reverse resoling the DN for a given loginname, something like (&(uid=%s)(ObjectClass=inetOrgPerson))

--rl_attrmap
    Resolver LDAP: the attribute mapping. Something like: { "username": "uid", "phone" : "telephoneNumber", "groups" : "o", "mobile" : "mobile", "email" : "mail", "surname" : "sn", "givenname" : "givenName" }

EXAMPLES

To list all know users you may issue a command like this:
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=listtoken

To import an XML file to your server, you need to do the following:
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=importtoken --file=mytoken.xml

To enroll a pytoken and assign it to the user 'hans' do this. This will output a python script (the pytoken) to stdout. The token will be assigned to the user 'hans' and when the token is used, the counter will we written to his home directory.
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=inittoken --user=hans --pytokeni

To enroll an eToken NG OTP and assign it to 'hans' do this. The serial number will be read from the smartcard of the eToken NG OTP.
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=inittoken --user=hans --etng

To set the OTP PIN to 'test' for a token with the serial number 003e7e4e do this:
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=set --serial=003e7e4e --pin=test

To set a new LDAP UserIdResolver, that contacts an LDAP server on 172.16.200.1 you could do it like this:
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=setresolver --resolver=newldap --rtype=LDAP --rl_uri='ldaps://172.16.200.1' --rl_basedn='dc=az,dc=local' --rl_binddn='cn=admin,dc=az,dc=local' --rl_bindpw='guessWhat' --rl_timeout=5 --rl_loginattr=uid --rl_searchfilter='(uid=*)(ObejctClass=inetOrgPerson)' --rl_userfilter='(&(uid=%s)(ObjectClass=inetOrgPerson))' --rl_attrmap='{ "username": "uid", "phone" : "telephoneNumber", "groups" : "o", "mobile" : "mobile", "email" : "mail", "surname" : "sn", "givenname" : "givenName" }'

Now you might want to add this UserIdResolver do a realm:
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=setrealm --realm=myRealm --resolver='useridresolveree.LDAPIdResolver.IdResolver.newldap'

If you want to make the new realm 'myRealm' the default realm do this:
    privacyideaadm.py --url=https://localhost:443 --admin=admin --command=setdefaultrealm --realm=myRealm

CONFIG FILE EXAMPLE
    [Default]
    protocol=https
    host=localhost
    admin=admin
    password=test123!
    command=listtoken
    csv_format=True
    mail_host=localhost
    mail_to=<email>
    mail_from=<email>
    mail_subject=some text
    cifs_server=your.file.server
    cifs_share=<share>
    cifs_dir=<directory>
    cifs_user=<username>
    cifs_password=<password>

INTERNET SOURCES
http://www.privacyidea.org, http://www.linotp.org

SEE ALSO
python (1)

BUGS
No known bugs.

AUTHOR
Cornelius Kölbel <cornelius@privacyidea.org>, LSE Leading Security Experts GmbH <linotp-community@lsexperts.de>, Cornelius Kölbel <cornelius.koelbel@lsexperts.de>