<< gsec commands | Firebird Password File Utility | Batch mode >>

Interactive mode

To run gsec in interactive mode, start the utility using the command line:

 C:\>gsec -user sysdba -password masterkey
 GSEC>

The GSEC> prompt shows that the utility is waiting for a command. The -user and -password options are those of the user who wishes to manipulate the security database. Obviously, the username supplied must be a valid SYSDBA user if updates are to be carried out. Normal users may only read the database.

Note: With Firebird 1.5 and Windows Vista this may not work correctly and an unavailable database error will be displayed. The problem is caused by trying to use the IPCServer transport implemented in Firebird 1.5 which doesn't work on Vista. The solution is to use TCP local loopback.

• Put an alias in aliases.conf for the path to your security.fdb, e.g. sec = C:\Program Files\Firebird\Firebird_1_5\security.fdb.
• Call gsec using gsec -database localhost:sec -user SYSDBA -password masterkey

As localhost may not be available on some Vista workstations you may have to change localhost in the command above to use the actual host name or the IP address of the Vista computer.

To exit gsec in interactive mode, the quit command is used:

 GSEC> quit
 C:\>

The following sections show how to carry out various commands in interactive mode. It is assumed that you are already running the utility as a SYSDBA user.

back to top of page

Displaying user details

Note: From Firebird 2.5 onwards, the display command shows an additional column named admin. This shows the text admin where a user has been granted the RDB$ADMIN role either within the database or by using gsec. In the following examples, where it is necessary to show this detail, it will be shown, otherwise, all output examples are as per Firebird 2.0.

To display all users in the security database the command and it's output are:

 GSEC> display
      user name       uid    gid           full name
 ------------------------------------------------------------------------
 SYSDBA               0      0
 NORMAN               0      0             Norman   Dunbar
 EPOCMAN              0      0             Benoit Gilles Mascia
 GSEC>

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

 GSEC> display epocman
      user name       uid    gid           full name
 ------------------------------------------------------------------------
 EPOCMAN              0      0             Benoit Gilles Mascia
 GSEC>

If you enter the name of a non-existent user as a parameter of the display command, nothing is displayed and gsec remains in interactive mode.

 GSEC> display alison
 GSEC>

back to top of page

Adding new users

When adding a new user in interactive mode, nothing is displayed to confirm that the user was indeed added. You need to use the display or display <name> commands to make sure that the user was added successfully.

 GSEC> add newuser -pw newuser -fname New -lname User
 GSEC> 

 GSEC> display newuser
      user name       uid    gid           full name
 ------------------------------------------------------------------------
 NEWUSER              0      0             New User
 GSEC> 

From Firebird 2.5 onwards, a new role - RDB$ADMIN - has been added to the security database. gsec allows you to indicate whether new users are assigned this role. The display command has also been modified to show whether a user had this role or not.

 GSEC> add newadmin -pw secret -fname New -mname admin -lname User -admin yes 
 GSEC>

 GSEC> display newadmin
     user name       uid     gid    admin     full name
 -----------------------------------------------------------------------
 NEWADMIN              0       0    admin     New admin User
 GSEC>

back to top of page

Deleting existing users

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

 GSEC> delete newuser
 GSEC>

 GSEC> display
      user name       uid    gid           full name
 ------------------------------------------------------------------------
 SYSDBA               0      0
 NORMAN               0      0             Norman Dunbar
 EPOCMAN              0      0             Benoit Gilles Mascia
 GSEC>

If, on the other hand, you try to delete a non-existing user, gsec will display an error message, and exit.

 GSEC> delete newuser
 record not found for user: NEWUSER

 C:\>

back to top of page

Amending existing users

Existing users can have one or more of their password, first name, middle name or lastname amended. There is no confirmation that your modification has worked, so you must use one of the display commands to determine how well it worked.

 GSEC> modify norman -pw newpassword
 GSEC>

 GSEC> modify norman -mname MiddleName -fname Fred
 GSEC>

 GSEC> display norman
      user name       uid    gid            full name
 ------------------------------------------------------------------------
 NORMAN               0      0              Fred MiddleName Dunbar
 GSEC>

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

 GSEC> modify norman -mname -fname -lname
 GSEC> display norman
      user name       uid    gid            full name
 ------------------------------------------------------------------------
 NORMAN               0      0

Now I can be known as 'the man with no name', just like Clint Eastwood!

From Firebird 2.5 onwards, a user's admin rights can be modified using this command:

 GSEC> modify norman -admin yes
 GSEC> display norman

     user name       uid     gid    admin     full name
 ----------------------------------------------------------------------
 NORMAN                0       0    admin     New admin User
 GSEC>

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.

From Firebird 2.5 they do not get these privileges automatically unless the DBA has configured the security database to make it happen automatically. This is done either in isql as follows:

 SQL> SQL> alter role rdb$admin set auto admin mapping;
 SQL> commit;

The command above will cause all Windows Administrator accounts to automatically have full access to the user management functions. The automatic mapping can be revoked as follows:

 SQL> SQL> alter role rdb$admin drop auto admin mapping;
 SQL> commit;

The functionality of the above isql commands can also be set using gsec, as follows, by using the -mapping command. The command takes a parameter of set or drop accordingly.

 GSEC> mapping set

or:

 GSEC> mapping drop

back to top of page

Help

The help command, in interactive mode, displays the same help screen as shown above. From Firebird 2.5, this can be abbreviated to a single question mark.

back to top of page

Version information

The version of gsec can be obtained using the z command.

 GSEC> z

 gsec version WI-V1.5.0.4306 Firebird 1.5 
 GSEC>

Or, in gsec from Firebird 2.5:

 GSEC> z

 gsec version LI-V2.5.0.26074 Firebird 2.5
 GSEC>

back to top of page
<< gsec commands | Firebird Password File Utility | Batch mode >>