Batch mode

<< Interactive mode | Firebird Password File Utility | Running gsec remotely >>

Batch mode

Note: In the following descriptions of batch mode operations, assume that I have set the ISC_USER and ISC_PASSWORD environment variables. This allows gsec to be run without always having to specify the -user and -password switches. This in turn reduces the amount of code on the command line, which means that when this XML file is rendered into pdf, all the command line will fit on the width of an A4 page.

It is not secure to have these variables set all the time, so don't do it !

Warning: If you are using gsec from Firebird version 1.5 (and possibly version 1.0 as well) then when you are running in batch mode, you may think that you can check the result of an operation by checking %ERRORLEVEL% in Windows, or $? in various flavours of Unix. This doesn't work. The result is always zero.

In gsec from Firebird version 2.0 onwards, this problem is fixed and the exit code will be zero for everything was ok, or a non-zero value for error conditions.

In batch mode, the command line to run gsec is as follows:

 gsec [ <options> ... ] <command> [ <parameter> ... ]


back to top of page

Displaying user details

To display all users in the security database the command, and its output are:

 C:\>gsec -display
      user name                 uid   gid       full name
 ------------------------------------------------------------------------
 SYSDBA                         0     0
 NORMAN                         0     0         Norman  Dunbar
 EPOCMAN                        0     0         Benoit Gilles Mascia

To display details of a single user, pass the username as a parameter to the display command.

 C:\>gsec -display epocman
      user name                 uid   gid       full name
 ------------------------------------------------------------------------
 EPOCMAN                        0     0         Benoit Gilles Mascia


back to top of page

Adding new users

When adding a user in batch mode, there is no confirmation that the user has been added. You should use the -display or -display <name> command to check.

 C:\>gsec -add newuser -pw newuser -fname New -lname User   

 C:\>gsec -display
      user name                 uid   gid       full name
 ------------------------------------------------------------------------
 SYSDBA                         0     0
 NORMAN                         0     0         Norman Dunbar
 NEWUSER                        0     0         New User
 EPOCMAN                        0     0         Benoit Gilles Mascia


Under Firebird 2.5, the -admin parameter may be specified:

 C:\>gsec -add newadmin -pw ignoreit -fname New -mname Admin -lname User -admin yes

 c:\>gsec -display newadmin
    user name        uid     gid    admin     full name
 ----------------------------------------------------------------------
 NEWADMIN              0       0              New Admin User


back to top of page

Deleting existing users

When deleting a user in batch mode, there is no confirmation that the user has been deleted. You should use the -display or -display <name> command to check.

 C:\>gsec -delete newuser

 C:\>gsec -display
      user name                 uid   gid        full name
 ------------------------------------------------------------------------
 SYSDBA                         0     0
 NORMAN                         0     0          Norman Dunbar
 EPOCMAN                        0     0          Benoit Gilles Mascia


back to top of page

Amending existing users

Existing users can have one or more of their password, first name, middle name, lastname or admin rights amended.

 C:\>gsec -modify norman -pw newpassword

 C:\>gsec -modify norman -mname MiddleName -fname Fred

 C:\>gsec -display
      user name                 uid    gid        full name
 ------------------------------------------------------------------------
 SYSDBA                         0      0
 NORMAN                         0      0          Fred MiddleName Dunbar
 EPOCMAN                        0      0          Benoit Gilles Mascia

If you wish to remove one or more of a user's attributes, don't pass a (new) value for that attribute.

 C:\>gsec -modify norman -mname -fname -lname

 C:\>gsec -display
      user name                 uid    gid        full name
 ------------------------------------------------------------------------
 SYSDBA                         0      0
 NORMAN                         0      0
 EPOCMAN                        0      0          Benoit Gilles Mascia

Now nobody knows who I am :o)

back to top of page

Version information

The version of gsec can be obtained using the -z command. However, note that it leaves you in interactive mode on completion. It doesn't exit like the other batch mode commands do, so you have to use the interactive quit command to exit. There is a way around this problem as shown in the following. The first part shows the problem - which still exists in Firebird 2.5.

 C:\>gsec -z
 gsec version  WI-V1.5.0.4306 Firebird 1.5
 GSEC>

The solution is to have a small file containing the command quit and force gsec to read this file when it needs user input, as follows:

 C:\>copy con fred
 quit
 ^Z
         1 file(s) copied.

 C:\>gsec -z <fred
 gsec version  WI-V1.5.0.4306 Firebird 1.5
 GSEC>
 C:\>

This could be a good idea for any of the commands which leave you 'stuck' in the interactive mode when you thought you were running in batch mode. By redirecting input from a command file, gsec will read a line of text from that file any time it requires user input. By forcing it to read the quit command, you make it exit.

Note: The -z command doesn't need a -user and -password, it will display the version details and then tell you that you don't have a username/password - but you can safely ignore this message.

back to top of page

OS admin mapping

Note: Firebird 2.5.

Since Firebird 2.1, Windows domain administrators have had full access to the user management functions. This meant that when an admin user connected to the server and then used gsec, they had the ability to modify any user account in the security database.

The functionality that allows Windows domain administrators to have full access to the user management functions of the Firebird's security database, can also be set using gsec on the command line as follows, by using the -mapping command. The command takes a parameter of set or drop accordingly.

 C:/> gsec -mapping set

or:

 C:/> gsec -mapping drop

back to top of page
<< Interactive mode | Firebird Password File Utility | Running gsec remotely >>