DFuserPerms

DFuserPerms
Prev	4.2. Alphabetical Listing	Next

DFuserPerms — Import and update users and passwords, and optionally import roles, role permissions, and user roles

Synopsis

DFuserPerms [-S server] [-U username] [-C password] [-a] [-f] [-e errorlog] {-i inputfile}

Description

Normally, creating and modifying users, passwords, roles, role permissions, and user roles is done with DFadmin. However, there may be cases where it would be useful to perform these operations from the command line. DFuserPerms is a tool that grants the ability to import these records from the command line. The records must be stored in an input file which conforms to the format used in the DFuserdb.log file (see System Administrator Guide, DFuserdb.logDFuserdb.log), although with the following exceptions:

Record Time Stamp and Record Modifier must not be included for any record type.
Instead of a Password Hash field for PASS records, the actual password to be imported must be specified.

	Important
The following behaviors of DFuserPerms should be noted: USRL and RLPM records require the corresponding ROLE record to be present in the same import file. However, PASS and USRL records do not require the corresponding USER to be present in the same file. For ROLE records, the role ID specified in the import file does not affect which ID it is actually assigned. If the role's name and study number matches an existing role, the existing role is edited to match the record being imported. If the role's combination of name and study number is new and unique, it is imported as a new role with the next available ID. As a result, role names cannot be edited with DFuserPerms. Though it does not matter to the ROLE record which ID it is given, if a USRL or RLPM record is being imported, the Role ID field is used to match it to a role imported in the same file. So if a user wishes to import USRL or RLPM records for a certain role, they must give the ROLE, RLPM, and USRL records the same role ID in their import file. See the second example. The Expiry field for PASS records is required but irrelevant. DFuserPerms sets the password expiry according to the settings in DFadmin. When there is an error in the record formatting or data, DFuserPerms does not import that specific record, but does import all other valid records in the file. As such, DFuserPerms is considered to have run successfully even if there are invalid records. Thus errors in the record formatting or data are not written to stderr, but rather stdout. Only errors which prevent DFuserPerms from running, such as authentication errors, are written to stderr. If there is an error when reading a PASS record, the password characters are replaced with X's when the error is written to stdout.

Important

The following behaviors of DFuserPerms should be noted:

USRL and RLPM records require the corresponding ROLE record to be present in the same import file. However, PASS and USRL records do not require the corresponding USER to be present in the same file.
For ROLE records, the role ID specified in the import file does not affect which ID it is actually assigned. If the role's name and study number matches an existing role, the existing role is edited to match the record being imported. If the role's combination of name and study number is new and unique, it is imported as a new role with the next available ID. As a result, role names cannot be edited with DFuserPerms.
Though it does not matter to the ROLE record which ID it is given, if a USRL or RLPM record is being imported, the Role ID field is used to match it to a role imported in the same file. So if a user wishes to import USRL or RLPM records for a certain role, they must give the ROLE, RLPM, and USRL records the same role ID in their import file. See the second example.
The Expiry field for PASS records is required but irrelevant. DFuserPerms sets the password expiry according to the settings in DFadmin.
When there is an error in the record formatting or data, DFuserPerms does not import that specific record, but does import all other valid records in the file. As such, DFuserPerms is considered to have run successfully even if there are invalid records. Thus errors in the record formatting or data are not written to stderr, but rather stdout. Only errors which prevent DFuserPerms from running, such as authentication errors, are written to stderr.
If there is an error when reading a PASS record, the password characters are replaced with X's when the error is written to stdout.

Options

-S server	the DFdiscover server name. Must be specified unless the user has the DFSERVER shell variable set appropriately.
-U username	login username. Must be specified unless the user has the DFUSER shell variable set appropriately.
-C password	login password. Must be specified unless the user has the DFPASSWD shell variable set appropriately, or has previously set up authentication using DFpass.
-a	allow ROLE, USRL, and RLPM records to be imported.
-f	check data format only. Does not import records. This option only looks for record formatting errors. Problems in the records that would need to be caught by the study server, such as passwords that do not meet the requirements or importing passwords for non-existent users, are not recognized by this option.
-e errorlog	output critical errors to specified file. Formatting errors are not written to the error log, only errors that prevent DFuserPerms from running. If this option is not specified, errors are written to stderr.
-i inputfile	specify the input file for DFuserPerms to import (required).

Exit Status

DFuserPerms exits with one of the following statuses:

0	The command was executed, DFuserPerms has run and imported all valid records. If there are invalid records but DFuserPerms has still run, the exit status is still 0.
1	DFuserPerms encountered a critical error such as failed authentication or permission errors. Invalid records in the import file are not critical errors since DFuserPerms still runs, and do not cause an exit status of 1.

Examples

Example 4.15. Importing USER and PASS records

In this example, a new user named Jason is imported and a password is assigned to them. The input file contains:

USER|Jason|2|Jason Johnson|A Company Incorporated|||||||||0|2|1|
PASS|Jason|apassword1234|1464208516

Importing the file:

% DFuserPerms -S servername -U username -C password -i inputfile

**********************************************************************
DFuserPerms: Server [servername] User [username] Fri Jun 10 09:40:37 2016
**********************************************************************
Input file: inputfile
Reading file
===============================
Imported Records = 2
Total Rows = 2
===============================

DONE: Importing user-perms complete. Errors (if any) are logged above.
**********************************************************************

Example 4.16. Importing ROLE, RLPM, and USRL records

In this example a new role called Company Permissions is imported, role permissions for this role are specified, and user Jason is assigned to have this user role. The input file contains:

ROLE|20|254|2|Company Permissions||*|*|*||*|0|0
RLPM|20|2|2|*|*|1,2,3,4,5|1,2,3,4,5|1,2,3,4|*|*|*|0|0
USRL|Jason|20|1|2|*|*

Importing the file:

% DFuserPerms -S servername -U username -C password -a -i inputfile

**********************************************************************
DFuserPerms: Server [servername] User [username] Fri Jun 10 09:51:27 2016
**********************************************************************
Input file: inputfile
Reading file
===============================
Imported Records = 3
Total Rows = 3
===============================

DONE: Importing user-perms complete. Errors (if any) are logged above.
**********************************************************************

Note that the ROLE, RLPM, and USRL records all used the same Role ID value (20). The DFuserdb.log file shows the the IDs have changed when they were imported, but DFuserPerms ensures that since they were imported with the same ID value, they are assigned to the same role ID (105):

20160610095127|ROLE|datafax|105|254|2|Company Permissions||*|*|*||*|0|0
20160610095127|RLPM|datafax|105|2|2|*|*|1,2,3,4,5|1,2,3,4,5|1,2,3,4|*|*|*|0|0
20160610095127|USRL|datafax|Jason|105|1|2|*|*

Prev	Up	Next
DFtiff2ras	Home	Chapter 5. Edit checks