Security administration utility

Use `sa_admin` to manage users, groups, and file permissions

Abstract

The command-line utility, sa_admin, manages users, groups, and file permissions. It is designed to run from the command line and from shell scripts in all supported operating systems.

Usage pattern

sa_admin [-a<adminUsername>] [-p<adminPassword>] [-f<filepassword>] [-1<obfuscatedPasswordFile>] [-s<serverName>] -<option>

Example 1. List all user accounts

sa_admin -aadmin -pADMIN -f"" -sFAIRCOMS -oul

-o option: action to perform

The -o flag specifies the action the sa_admin utility performs. It is required. The -o is followed directly by two or three characters, which identify the action. For example, the -oul option lists all user accounts.

Table 1. All possible actions

Category	Option	Description
Account	`-oua`	Add a user account
	`-oud`	Change user account description
	`-oue`	Change user account extended settings
	`-oug`	Add a user to a group
	`-oul`	List user accounts
	`-oum`	Change user account memory limit
	`-oup`	Change user account password
	`-our`	Delete a user account
	`-ous`	Show user account information
	`-oux`	Remove a user from a group
Group	`-ofg`	Change file group
	`-oga`	Add a group
	`-ogd`	Change group description
	`-ogl`	List groups
	`-ogm`	Change group memory limit
	`-ogr`	Delete a group
	`-ogs`	Show group information
	`-oug`	Add a user to a group
	`-oux`	Remove a user from a group
File	`-ofg`	Change file group
	`-ofl`	List files matching filename
	`-oflp`	List file permissions mask
	`-ofo`	Change file owner
	`-ofp`	Change file password
	`-ofs`	Change file permissions

Connection options

Note

These flags should be followed directly by the parameter. No space. I.E. -pMyPassword.

Command line option	Description	Default
`-a`	System administrator user ID	Required - No default value
`-f`	Server system file password	Defaults to no password
`-p`	System administrator password	Required - No default value
`-s`	Server name	`"FAIRCOMS"`

-1 option: obfuscated password file

The -1 option specifies the filename of an obfuscated password file. The file name is quoted and follows the flag without a space — for example, -1"my_password_file.set". The password file is first obfuscated by the ctcmdset command line utility, see ctcmdset.

Example 5. Contents of a password file

Before obfuscation, the password file should have a text format similar to the following:

; Account Name
USERID ADMIN
; Password
PASSWD <pass>

An obfuscated password file is typically used in scripts to prevent having to embed inline account names and passwords.

Example 6. Use an encrypted password file

sa_admin -1"my_password_file.set" -sFAIRCOMS -oul

Account management

This section lists options, all beginning with -ou, that allow changes to user information. Additional group and file options are also described.

Note

To use any optional entry, you must use all the previous entries even if they would otherwise be optional. For example, to add a user with the -oua option and specify a group, you must also enter the userid, desc, and password.

Table 2. Account management actions

Option	Description
`-oua`	Add a user account
`-oud`	Change user account description
`-oue`	Change user account extended settings
`-oug`	Add a user to a group
`-oul`	List user accounts
`-oum`	Change user account memory limit
`-oup`	Change user account password
`-our`	Delete a user account
`-ous`	Show user account information
`-oux`	Remove a user from a group

-oua option: user add

sa_admin [-a<adminuserid>] [-p<adminpassword>] [-f<filepassword>] [-s<servername>] -oua <userid> <option>

Command line option

Description

Default

userid

User ID

Required - No default value

-d "desc"

User description, must be quoted with a single space after the flag.

Defaults to no description

-w password

User password, not quoted with a single space after the flag.

Optional

-g group

User group, not quoted. Follows the flag with NO space.

Optional

-m <bytes>{a|d|g}

User memory limit in bytes followed directly by an optional rule letter.

Defaults to unlimited

rule

a for absolute - The user is limited to this amount of memory.

d for default - There is a system-wide setting for which rule will be the default. Selecting d or leaving the memory rule off will set the user to the default rule. If d is not specified, the default is guideline.

g for guideline - The user can have more memory than this, but it may be reduced to the provided guideline if necessary. This is the default when d is not specified.

For example, -m 10485760a specifies an absolute memory limit of 10 MB

Defaults to the system-wide default rule

-b begdate

Starting validity date, specified as mm/dd/yyyy

Defaults to no date restriction

-e enddate

Ending validity date, specified as mm/dd/yyyy

Defaults to no date restriction

-l loglimit

Maximum invalid logon attempts

0 for default

-1 to disable invalid logon check

Defaults to unlimited

-r rsmlogon

Remaining logon block period in minutes

Note

Specifying a value of "block" (for example, -r block) blocks the account indefinitely (until it is unblocked by an administrator, and specifying a value of "unblock" (for example, -r unblock) unblocks the account immediately.

Defaults to no block

-t mustlogon

Interval in minutes during which the user must logon at least once, otherwise the account is blocked — for example, a setting of 60 would cause any logon attempts that occur longer than 60 minutes from a previous successful logon to fail and block the user.

NULL for default

-1 to disable must logon period

Defaults to no required logon

Example 7. Add an account using default values

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user1

Example 8. Add an account with a description, password, and group

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user2 -d "description" -w password -g group1

Example 9. Add an account with flexible memory limits, a starting effectively date, and an ending effectively date

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user3 -m 5000000g -b 01/31/2022 -e 02/20/2022

Example 10. Add an account and block its ability to log in

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user4 -l 10 -r unblock -t 15

Example 11. Blocking users

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user1 -r block

Example 12. Unblocking users

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user1 -r unblock

-oug option: add user to group

-oug userid group

Command line option	Description	Default
`userid`	User ID	Required - No default value
`group`	User group, not quoted. Follows the flag with NO space.	Required - No default value

Example 14. Option add user to group

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user1 group1

-oup option: user change password

-oup userid password

Command line option	Description	Default
`userid`	User ID	Required - No default value
`password`	User password, not quoted with a single space after the flag.	Required - No default value

Example 16. Option user change password

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oup user1 newPassword

-oux option user (group) extract: remove a user from a group

-oux userid group

Command line option	Description	Default
`userid`	User ID	Required - No default value
`group`	User group, not quoted. Follows the flag with NO space.	Required - No default value

Example 17. Option user (group) extract

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oux user1 group1

-oud option: user change description

-oud userid desc

Command line option	Description	Default
`userid`	User ID	Required - No default value
`desc`	User description, must be quoted with a single space after the flag.	Defaults to no description

Example 18. Option user change description

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oud user1 "My new description for user1"

-oum option: user change memory limit

-oum userid [-m memory[rule]]

Command line option

Description

Default

userid

User ID

Required - No default value

memory

User memory limit in bytes followed directly by an optional rule letter.

Defaults to unlimited

rule

a for absolute - The user is limited to this amount of memory.

g for guideline - The user can have more memory than this, but it may be reduced to the provided guideline if necessary. This is the default when d is not specified.

For example, -m 10485760a specifies an absolute memory limit of 10 MB

Defaults to system-wide default rule

Example 19. Change user1 to 5 MiB as a guideline

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user1 -m 5000000g

Example 20. Change user2 to unlimited

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user2

Example 21. Change user4 to 2 MiB absolute fixed limit

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user4 -m 2000000a

-oue option: user change extended settings

-oue <userid> [-b <begdat>] [-e <enddat>] [-l <loglimit>] [-r <rsmlogon>] [-t <mstlogon>]

Command line option

Description

Default

userid

User ID

Required - No default value

-b begdate

Starting validity date, specified as mm/dd/yyyy

Defaults to no date restriction

-e enddate

Ending validity date, specified as mm/dd/yyyy

NULL for default

Defaults to no date restriction

-l loglimit

Maximum invalid logon attempts

0 for default

-1 to disable invalid logon check

Defaults to unlimited

-t mustlogon

NULL for default

-1 to disable must logon period

Defaults to no required logon

-r rsmlogon

Remaining logon block period in minutes

Note

Defaults to no block

Example 22. Edit a user to have a starting effectively date, and ending effectively date with a no-login period of 1 minute after 10 failed login attempt. With the user needing to login every 15 minutes to prevent the account from becoming blocked:

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -b 01/31/2022 -e 02/20/2022 -r 1 -l 10 -t 15

Example 23. Blocking users

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -r block

Example 24. Unblocking users

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -r unblock

Security group management

Note

To use any optional entry, you must use all the previous entries. For example, to specify a rule when adding a group with the -oga option, you must also enter the desc and memory options for the group.

This section lists options, all beginning with -og, allow changes to group information. Additional user and file options are described elsewhere.

Table 3. Security group management actions

Option	Description
`-ofg`	Change file group
`-oga`	Add a group
`-ogd`	Change group description
`-ogl`	List groups
`-ogm`	Change group memory limit
`-ogr`	Delete a group
`-ogs`	Show group information
`-oug`	Add a user to a group
`-oux`	Remove a user from a group

-ofg option: file group

-ofg filename groupid

Command line option	Description	Default
`filename`	File name	Required - No default value
`groupid`	Group ID	Required - No default value

Example 26. Option file group

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofg "C:\FairCom\data\db1.dbs\owner1_table2.dat"  OWNER1_RWD

-oga option: group add

-oga <groupid> [-d <desc>] [-m <memory>][<rule>]]

Command line option

Description

Default

groupid

Group ID

Required - No default value

-d desc

Group description

Defaults to no description

memory

Memory limit

Defaults to unlimited

rule

a for absolute - The user is limited to this amount of memory.

g for guideline - The user can have more memory than this, but it may be reduced to the provided guideline if necessary. This is the default when d is not specified.

For example, -m 10485760a specifies an absolute memory limit of 10 MB

Defaults to the system-wide default rule

Example 27. Adding a group

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS  -oga group1

Example 28. Adding a group with a description and an absolute memory limit

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS  -oga group2 -d "Description for group2" -m 10485760a

-ogd option: group change description

-ogd groupid desc

Command line option	Description	Default
`groupid`	Group ID	Required - No default value
`desc`	New group description	Defaults to no description

Example 31. Option group change description

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS  -ogd group1 "group1 description"

-ogm option: group memory

-ogm groupid [-m <memory>[<rule>]]

Command line option

Description

Default

groupid

Group ID

Required - No default value

-m memory

New memory limit

Defaults to unlimited

rule

a for absolute - The user is limited to this amount of memory.

g for guideline - The user can have more memory than this, but it may be reduced to the provided guideline if necessary. This is the default when d is not specified.

For example, -m 10485760a specifies an absolute memory limit of 10 MB

Defaults to the system-wide default rule

Example 32. Setting a guideline group1 memory to 5000000g

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS  -ogm group1 -m 5000000g

Example 33. Setting a guideline group2 memory to the default

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS  -ogm group2 -m d

-oug option: add user to group

-oug userid group

Command line option	Description	Default
`userid`	User ID	Required - No default value
`group`	User group, not quoted. Follows the flag with NO space.	Required - No default value

Example 35. Option add user to group

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user1 group1

-oux option user (group) extract: remove a user from a group

-oux userid group

Command line option	Description	Default
`userid`	User ID	Required - No default value
`group`	User group, not quoted. Follows the flag with NO space.	Required - No default value

Example 36. Option user (group) extract

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oux user1 group1

File security management

This section lists the options, all beginning with -of, for allowing changes to file information. Additional user and group option are described elsewhere.

Table 4. File security management actions

Option	Description
`-ofg`	Change file group
`-ofl`	List files matching filename
`-oflp`	List file permissions mask
`-ofo`	Change file owner
`-ofp`	Change file password
`-ofs`	Change file permissions

Example 37. -ofs <filename> <permmask> is the same as current usage:

-ofs test.dat ++++++++++-----

Example 38. Set all owner and group permissions and resets all world permissions:

Note

-ofs <filename> <permission> ... sets the file permissions to the specified permissions

-ofs test.dat ownerall groupall

Example 39. Add the worldread permission to the current file permissions and removes the groupwrite permission from the current file permissions:

Note

-ofs <filename> +|- <permission> ... adds/removes specified permissions to/from current file permissions.

-ofs test.dat +worldread -groupwrite

-ofp option: filename password

-ofp filename password

Command line option	Description	Default
`filename`	File name	Required - No default value
`password`	File password	Required - No default value

Example 40. Set new password

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofp "C:\FairCom\data\db1.dbs\owner1_table2.dat"  mynewpassword

Example 41. Remove password

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofp "C:\FairCom\data\db1.dbs\owner1_table2.dat" ""

-ofs options : filename permission

-ofs <filename> <permission> ...

-ofs +|-<permission> ...

Command line option	Description	Default	Notes
`filename`	File name	Required - No default value
`permission`	File permission mask	Optional	To set a permission, set the byte at the corresponding offset to a value of `+`. To reset a specified permission, set the corresponding byte to `-`.

Important

Options are evaluated left to right.

Specifying -groupwrite +groupwrite has the effect of adding the groupwrite permission, and specifying +worldall -worldread turns on all world permissions except read permission.

Example 42. The string +++++-----+++++ sets all OWNER and WORLD permissions, and clears all GROUP permissions:

This field is interpreted as a 15-byte permission mask containing owner, group, and world permissions.

      (offset)

      0  1  2  3  4  5  6  7  8  9  10 11 12 13 14

      ----OWNER----  ----GROUP----  -----WORLD----

      r  w  f  d  p  r  w  f  d  p   r  w  f  d  p

     

      r = Read  w = Write  f = define  d = Delete  p = noPass

Example 43. Remove all file permissions:

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" -ownerall -groupall -worldall

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" ---------------

Example 44. Set all file permissions:

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +ownerall +groupall +worldall

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +++++++++++++++

Example 45. Set typical file permissions to owner ALL, group RWDP, world R:

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +ownerall +groupall -groupdefine -worldall +worldread

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofs "C:\FairCom\data\db1.dbs\owner1_table2.dat" +++++++-+++----

-ofg option: file group

-ofg filename groupid

Command line option	Description	Default
`filename`	File name	Required - No default value
`groupid`	Group ID	Required - No default value

Example 46. Option file group

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofg "C:\FairCom\data\db1.dbs\owner1_table2.dat"  OWNER1_RWD

-ofo option: filename owner

-ofo filename owner

Command line option	Description	Default
`filename`	File name	Required - No default value
`owner`	File owner	Required - No default value

Example 47. Option file owner

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofo "C:\FairCom\data\db1.dbs\owner1_table2.dat"  OWNER1

Tips and helpful examples

Using `-ofs` to clear the permission mask

Sometimes it is desirable to make the permission mask empty instead of just adding more permissions to allow all access.

Example 48. Consider a file with this permission mask, which has permissions for "owner" and "world"

Permission mask    = 0x2783e = {owner: read write def deleteworld: read write def delete nopass}

Example 49. To remove all permissions for "owner" and "world" you can use the -ofs option as follows:

sa_admin -aadmin -pADMIN -f"" -sFAIRCOMS -ofs ./ctreeSQL.dbs/admin_permTest.dat -worldall -ownerall

Example 50. -worldall removes all permissions for "world" and -ownerall removes all permissions for "owner". The resulting permission mask will be as follows:

Permission mask    = 0x421 = {}

Example 51. To clear permissions for world, user, and group, use the following:

sa_admin -aadmin -pADMIN -f"" -sFAIRCOMS -ofs ./ctreeSQL.dbs/admin_permTest.dat -worldall -ownerall -groupall

Display file permissions

C:\> sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oflp "vcust*"

Permission mask for file vcusti: OPF_READ OPF_WRITE OPF_DEF OPF_DELETE GPF_READ GPF_WRITE WPF_READ

Permission mask for file vcusti.2: OPF_READ OPF_WRITE OPF_DEF OPF_DELETE GPF_READ GPF_WRITE WPF_READ

Permission mask for file vcusti.ndx: OPF_READ OPF_WRITE OPF_DEF OPF_DELETE GPF_READ GPF_WRITE WPF_READ

Security administration utility

Use sa_admin to manage users, groups, and file permissions

Usage pattern

-o option: action to perform

Connection options

Note

-a option: account name

-f option: file password

-p option: password

-s option: server name

-1 option: obfuscated password file

Account management

Note

-oua option: user add

Note

-our option: user remove

-oug option: add user to group

-oul option: user list

-oup option: user change password

-oux option user (group) extract: remove a user from a group

-oud option: user change description

-oum option: user change memory limit

-oue option: user change extended settings

Note

-ous option: user show

Security group management

Note

-ofg option: file group

-oga option: group add

-ogr option: group remove

-ogl option: group list

-ogd option: group change description

-ogm option: group memory

-ogs option: group show

-oug option: add user to group

-oux option user (group) extract: remove a user from a group

File security management

Note

Note

-ofp option: filename password

-ofs options : filename permission

Important

-ofg option: file group

-ofo option: filename owner

Tips and helpful examples

Using Wildcards for filenames

Retrieving a list of filenames

Using -ofs to clear the permission mask

Display file permissions

Use `sa_admin` to manage users, groups, and file permissions

Using `-ofs` to clear the permission mask