Firebird Documentation IndexFirebird 2.1 Release NotesCommand-line Utilities → Firebird Services
Firebird Home Firebird Home Prev: Command-line UtilitiesFirebird Documentation IndexUp: Command-line UtilitiesNext: Backup Tools

Firebird Services

New Command-line Utility fbsvcmgr

New Command-line Utility fbsvcmgr

Alex Peshkov

(V.2.1) The new utility fbsvcmgr provides a command-line interface to the Services API, enabling access to any service that is implemented in Firebird.

Although there are numerous database administration tools around that surface the Services API through graphical interfaces, the new tool addresses the problem for admins needing to access remote Unix servers in broad networks through a text-only connection. Previously, meeting such a requirement needed a programmer.

Using fbsvcmgr

fbsvcmgr does not emulate the switches implemented in the traditional “g*” utilities. Rather, it is just a front-end through which the Services API functions and parameters can pass. Users therefore need to be familiar with the Services API as it stands currently. The API header file—ibase.h, in the ../include directory of your Firebird installation— should be regarded as the primary source of information about what is available, backed up by the InterBase 6.0 beta API Guide.

Specify the Services Manager

The first required parameter for a command line call is the Services Manager you want to connect to:

  • For a local connection use the simple symbol service_mgr

  • To attach to a remote host, use the format hostname:service_mgr

Specify subsequent service parameter blocks (SPBs)

Subsequent SPBs, with values if required, follow. Any SPB can be optionally prefixed with a single '-' symbol. For the long command lines that are typical for fbsvcmgr, use of the '-' improves the readability of the command line. Compare, for example, the following (each a single command line despite the line breaks printed here):

# fbsvcmgr service_mgr user sysdba password masterke
        action_db_stats dbname employee sts_hdr_pages


# fbsvcmgr service_mgr -user sysdba -password masterke
        -action_db_stats -dbname employee -sts_hdr_pages
SPB Syntax

The SPB syntax that fbsvcmgr understands closely matches with what you would encounter in the ibase.h include file or the InterBase 6.0 API documentation, except that a slightly abbreviated form is used to reduce typing and shorten the command lines a little. Here's how it works.

All SPB parameters have one of two forms: (1) isc_spb_VALUE or (2) isc_VALUE1_svc_VALUE2. For fbsvcmgr you just need to pick out the VALUE, VALUE1 or VALUE2 part[s] when you supply your parameter.

Accordingly, for (1) you would type simply VALUE, while for (2) you would type VALUE1_VALUE2. For example:

isc_spb_dbname => dbname
isc_action_svc_backup => action_backup
isc_spb_sec_username => sec_username
isc_info_svc_get_env_lock => info_get_env_lock

and so on.


An exception is isc_spb_user_name: it can be specified as either user_name or simply user.

It is not realistic to attempt to describe all of the SPB parameters in release notes. In the InterBase 6.0 beta documentation it takes about 40 pages! The next section highlights some known differences between the operation of fbsvcmgr and what you might otherwise infer from the old beta documentation.

fbsvcmgr Syntax Specifics
Do's and Don'ts

With fbsvcmgr you can perform a single action—and get its results if applicable—or you can use it to retrieve multiple information items from the Services Manager. You cannot do both in a single command.

For example,

# fbsvcmgr service_mgr -user sysdba -password masterke

will list all current users on the local firebird server:

SYSDBA                         Sql Server Administrator      0    0
QA_USER1                                                     0    0
QA_USER2                                                     0    0
QA_USER3                                                     0    0
QA_USER4                                                     0    0
QA_USER5                                                     0    0
GUEST                                                        0    0
SHUT1                                                        0    0
SHUT2                                                        0    0
QATEST                                                       0    0


# fbsvcmgr service_mgr -user sysdba -password masterke
    -info_server_version -info_implementation

will report both the server version and its implementation:

Server version: LI-T2.1.0.15740 Firebird 2.1 Alpha 1
Server implementation: Firebird/linux AMD64

But an attempt to mix all of this in single command line:

# fbsvcmgr service_mgr -user sysdba -password masterke
    -action_display_user -info_server_version -info_implementation

raises an error:

Unknown switch “-info_server_version
Undocumented Items

The function isc_spb_rpr_list_limbo_trans was omitted from the IB6 beta documentation. It is supported in fbsvcmgr.

Support for New Services API Items in v.2.1

Two new items that were added to the Services API in Firebird 2.1 are supported by fbsvcmgr:

  • isc_spb_trusted_auth (type it as trusted_auth) applies only to Windows. It forces Firebird to use Windows trusted authentication.

  • isc_spb_dbname gives the ability to set a database name parameter (type as dbname) in all service actions related to accessing the security database from a remote client, equivalent to supplying the -database switch to the gsec utility.


    For gsec the -database switch is mostly used to specify a remote server you want to administer. In fbsvcmgr, the name of the server is already given in the first parameter (via the service_mgr symbol) so the [isc_spb_]dbname parameter is mostly unnecessary.

Documentation Bugs

The format described for some parameters in the InterBase 6 beta documentation are buggy. When in trouble, treat ibase.h as the primary source for the correct form.

Unsupported functions
  • Everything to do with licensing was removed from the original InterBase 6 open source code and is therefore not supported either in Firebird or by fbsvcmgr.

  • The old Config file view/modification functions have been unsupported since Firebird 1.5 and are not implemented by fbsvcmgr.

Backup Service Misbehaviour Fixed

A. Peshkov

Feature request CORE-1232

(V.2.1) Some misbehaviours that could occur when the Services Manager was doing backup/restore operations and some parameter items were missing or in the wrong sequence. The problem still affects lower versions, including v.2.0.x, so care should be taken to specify all required switches and supply the database name and backup file spec in the correct order when using the -se[vice_mgr] switch.

Disable Non-SYSDBA Access to Privileged Services

A. Peshkov

Feature request CORE-787

Non-SYSDBA access to parts of the Services API that return information about users and database paths has been disabled. A non-privileged user can retrieve information about itself, however.

Prev: Command-line UtilitiesFirebird Documentation IndexUp: Command-line UtilitiesNext: Backup Tools
Firebird Documentation IndexFirebird 2.1 Release NotesCommand-line Utilities → Firebird Services