Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

sa_admin - Command-line security administration utility

The command-line version of the system administrator program, sa_admin, can be used to perform many user operations directly from shell scripts.

Operational Model:

  • Client

Usage:

sa_admin [-a<adminuserid>] [-p<adminpassword>] [-f<filepassword>] [-s<servername>] [-S BASIC | <cert_filename>] <option>

option is one of the following:

Options Users

  • -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

Options 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

Options 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

Wildcard specifiers with sa_admin

sa_admin, -ofp, -ofs, -ofg, and -ofo options support specifying filenames with wildcard characters. When one of these options specifies a filename that includes ? or * characters, the utility retrieves a list of files matching the filename wildcard specifier and executes the specified command for each file.

Retrieve a List of Filenames from the server with sa_admin

-ofl (list files) is used to list the files on the FairCom Server system matching the specified filename including wildcard characters.

sa_admin Support for Encrypted Password Files

This utility supports the use of an encrypted password file. Encrypted password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:

; User Id
USERID ADMIN
; User Password
PASSWD <pass>

Use the -1 option to specify the name of the encrypted file. The encrypted password file name is specified using the command-line option:

-1 <filename>

TLS Security

  • -S - TLS/SSL options for secure connection:
    • BASIC - Basic TLS/SSL encryption
    • <cert_filename> - Client cross-check certificate for TLS authentication

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. For example, consider a file with this permission mask, which has permissions for "owner" and "world":

Permission mask = 0x2783e = {

owner: read write def delete

world: read write def delete nopass

}

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

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

Permission mask = 0x421 = {

}

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

In This Section

Administrator Options

User Options

Group Options

File Options

Previous Topic

Next Topic

Administrator Options

  • -a System administrator User ID.
  • -p System administrator password.
  • -f Optional server system file password.
  • -s Optional server name.

Note: There is no space between the switch and its parameter.

Previous Topic

Next Topic

User Options

The following options, all beginning with -ou, allow changes to user information. Additional group and file options are described below.

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.

Option User Add

-oua <userid> [-d <desc>] [-w <password>] [-g <group>] [-m <memory>[<rule>]]
[-b <begdat>] [-e <enddat>] [-l <loglimit>] [-r <rsmlogon>] [-t <mstlogon>]

  • userid: User id (required)
  • -d desc: Optional user description
  • -w password: Optional user password
  • -g group: Optional user group
  • -m memory: Optional user memory limit.
    • rule: Optional user memory rule. Used only with memory. The optional <rule> is A for absolute, D for default, or G for guideline (example -m 10485760a specifies an absolute memory limit of 10 MB). NULL for Default.
  • -b begdat: Optional starting validity date. Specify as mm/dd/yyyy. NULL for Default.
  • -e enddat: Optional ending validity date. Specify as mm/dd/yyyy. NULL for Default.
  • -l loglimit: Optional maximum invalid logon attempts. NULL for Default.
  • -r rsmlogon is the logon block period in minutes. Specifying a value of “block” (e.g., -r block) blocks the account indefinitely (until it is unblocked by an administrator, and specifying a value of “unblock” (e.g., -r unblock) unblocks the account immediately.
  • -t mstlogon is the interval in minutes during which the user must logon at least once, otherwise the account is blocked.
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user1

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

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

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oua user4 -l 10 -r unblock -t 15
  • Example for blocking users:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -r block
  • Example for unblocking users:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -r unblock

Option User Remove

-our userid

  • userid: User id (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -our user1

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

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -our user3

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -our user4

Option User List

-oul

  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oul

Option User Change Password

-oup userid password

  • userid: User id (required)
  • password: New password (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oup user1 mynewpassword

Option User Add user to Group

-oug userid group

  • userid: User id (required)
  • group: Group name (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user1 group1

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

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user3 group2

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oug user4 group2

Option User (Group) Extract - Remove a user from a group

-oux userid group

  • userid: User id (required)
  • group: Group name (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oux user1 group1

Option User Change Description

-oud userid desc

  • userid: User id (required)
  • desc: New user description
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oud user1 "My new description for user1"

Option User Memory

-oum userid -m memory rule

  • userid: User id (required)
  • memory: New memory limit. This can be a number of bytes or ‘D’ for default or left NULL for no limit
  • rule: Optional user memory rule. Used only with memory. This may be ‘A’ for Absolute, ‘G’ for Guideline, ‘D’ for Default, or NULL for Default
  • Example:
    change user1 to 5 MiB as a Guideline

    change user2 to unlimited

    change user3 to default limit

    change user4 to 2 MiB absolute fixed limit

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

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

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oum user3 -m d

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

Option User Change Extended Settings

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

  • userid: User id (required)
  • -b begdat: Optional starting validity date. Specify as mm/dd/yyyy. NULL for Default
  • -e enddat: Optional ending validity date. Specify as mm/dd/yyyy. NULL for Default
  • -l loglimit: Optional maximum invalid logon attempts. 0 for Default. -1 to disable invalid logon check.
  • -t mstlogon: Optional must logon period, e.g., how often the user must log on to remain active. The interval in minutes during which the user must logon at least once, otherwise the account is blocked. Specify as number of minutes. NULL for Default. -1 to disable must logon period.
  • -r rsmlogon: Optional logon timeout remaining. If a user has been denied access to the FairCom Server due to excessive invalid logon attempts, you can adjust the remaining user lockout time here. Specify as number of minutes. NULL to leave unchanged. Specifying a value of “block” (e.g., -r block) blocks the account indefinitely (until it is unblocked by an administrator), and specifying a value of “unblock” (e.g., -r unblock) unblocks the account immediately.
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oue user1 -b 01/31/2022 -e 02/20/2022 -l 10 -r 1 -t 15

Option User Show

-ous userid

  • userid: User id (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ous user1

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

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ous user3

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ous user4

Previous Topic

Next Topic

Group Options

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

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.

Option Group Add

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

  • groupid: Group id (required)
  • -d desc: Optional group description
  • memory is the memory limit and the optional <rule> is A for absolute, D for default, or G for guideline (example -m 10485760a specifies an absolute memory limit of 10 MB).
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oga group1
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oga group2 -d "Description for group2" -m 10485760a

Option Group Remove

-ogr groupid

  • groupid: Group id (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogr group1

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogr group2

Option Groups List

-ogl

  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogl

Option Group Change Description

-ogd groupid desc

  • groupid: Group id (required)
  • desc: New group description
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogd group1 -d "group1 description"

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogd group2 -d "group2 description"

Option Group Memory

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

  • groupid: Group id (required)
  • -m memory: New memory limit. memory is the memory limit
    • <rule> (optional) is A for absolute, D for default, or G for guideline (example -m 10485760a specifies an absolute memory limit of 10 MB).
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogm group1 -m 5000000g

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

Option Group Show

-ogs groupid

  • groupid: Group id (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogs group1

    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ogs group2

Previous Topic

Next Topic

File Options

The following options, all beginning with -of, allow changes to file information. Additional user and group options are described elsewhere.

Option File Password

-ofp filename password

  • filename: File name (required)
  • password: File password (required)
  • Example:
    Set new password:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofp "C:\FairCom\data\db1.dbs\owner1_table2.dat" mynewpassword

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

Option File Security (permissions)

-ofs <filename> <permission> ...

-ofs +|-<permission> ...

  • filename: File name (required)
  • permission: File permission mask.
    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 ‘-’.
    For example, 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

  • permission can also be one of the following:

ownerall, ownerread, ownerwrite, ownerdefine, ownerdelete, ownernopass,

groupall, groupread, groupwrite, groupdefine, groupdelete, groupnopass,

worldall, worldread, worldwrite, worlddefine, worlddelete, worldnopass

Options are evaluated left to right. For example, specifying -groupwrite +groupwrite has the effect of adding the groupwrite permission, and specifying +worldall -worldread turns on all world permissions except read permission.

  • Example - 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 - 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 - set typical file permissions: 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" +++++++-+++----

Option File Group

-ofg filename groupid

  • filename: File name (required)
  • groupid: File group id (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofg "C:\FairCom\data\db1.dbs\owner1_table2.dat" OWNER1_RWD

Option File Owner

-ofo filename owner

  • filename: File name (required)
  • owner: File owner (required)
  • Example:
    sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -ofo "C:\FairCom\data\db1.dbs\owner1_table2.dat" OWNER1

Examples of -ofs usage:

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

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

-ofs <filename> <permission> ... sets the file permissions to the specified permissions. The following command sets all owner and group permissions and resets all world permissions:

-ofs test.dat ownerall groupall

-ofs <filename> +|- <permission> ... adds/removes specified permissions to/from current file permissions. The following command adds the worldread permission to the current file permissions and removes the groupwrite permission from the current file permissions:

-ofs test.dat +worldread -groupwrite

TOCIndex