| Firebird Documentation Index → Firebird 2.1 Release Notes → Command-line Utilities → Firebird Services |
|
|
|
(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.
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.
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
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
and
# fbsvcmgr service_mgr -user sysdba -password masterke
-action_db_stats -dbname employee -sts_hdr_pages
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.
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
-action_display_user
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
...and...
# 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”
The function isc_spb_rpr_list_limbo_trans was omitted from
the IB6 beta documentation. It is supported in fbsvcmgr.
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.
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.
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.
(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.
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.
|
| Firebird Documentation Index → Firebird 2.1 Release Notes → Command-line Utilities → Firebird Services |