<< International Language Support (INTL) | Firebird 2.5.3 Release Notes | Installation notes >>

Command-line utilities

Incompatibility with older clients: To enable the 32-bit tools to work correctly with new structures that enable statistics routines to work properly with a 64-bit server, it was necessary to introduce some new internal API functions (struct perf64 and perf64_xxx) and change isql and qli to use them. This means that the isql and qli programs in v.2.5 are not compatible with older Firebird clients.

For more information, see the topic Statistics now work properly with 64-bit values in the Engine chapter.

fbtracemgr

Vlad Khorsun

Tracker reference CORE-2524.

This is a new CLI utility for interfacing with the new trace facilities.

Usage is as follows:

 fbtracemgr <action> [<parameters>]

Action switches

 -STA[RT]     Start trace session
 -STO[P]      Stop trace session
 -SU[SPEND]   Suspend trace session
 -R[ESUME]    Resume trace session
 -L[IST]      List existing trace sessions

Parameters

Action parameters

 -N[AME]      <string>   Session name
 -I[D]        <number>   Session ID
 -C[ONFIG]    <string>   Trace configuration file name

Connection parameters

 -SE[RVICE]   <string>   Service name
 -U[SER]      <string>   User name
 -P[ASSWORD]  <string>   Password
 -FE[TCH]     <string>   Fetch password from file
 -T[RUSTED]   <string>   Force trusted authentication

Examples using fbtracemgr

 fbtracemgr -SE remote_host:service_mgr -USER SYSDBA -PASS masterkey -LIST
 fbtracemgr -SE service_mgr -START -NAME my_trace -CONFIG my_cfg.txt
 fbtracemgr -SE service_mgr -SUSPEND -ID 2
 fbtracemgr -SE service_mgr -RESUME -ID 2
 fbtracemgr -SE service_mgr -STOP -ID 4

Notes:

1. All switches and parameter identifiers are case-insensitive.
2. To stop an interactive trace session on any platform, press [Ctrl + C].

V.2.5.1 improvements

The diagnostics of internal trace errors were improved. (Tracker reference CORE-3413).

Output is now flushed periodically. (Tracker reference CORE-3324).

back to top of page

Retrieve password from a file or prompt

Alex Peshkov

Any command-line utility that takes a -password parameter is vulnerable to password sniffing, especially when the utility is run from a script. Since v.2.1, the [PASSWORD] argument has displayed in the process list on POSIX platforms as an asterisk ( * ), which was an improvement on showing it in clear.

As a second stage towards hiding the password from unauthorised eyes, this release enables it to be retrieved from a file or (on POSIX) from STDIN.

New -fetch_password switch

Firebird 2.5 introduces the new switch -fet[ch_password] as an optional replacement for -pa[ssword] for all command-line utilities that take a password for authentication purposes. The switch may be progressively abbreviated from the right, conforming to the established rules.

PLEASE NOTE:
1. The exception to the rules is the qli utility, for which only -F is valid.
2. The new switch cannot be applied to substitute for the -pw switch of the gsec utility.

Usage of -fetch_password

The switch requires one parameter, an unquoted string that is the file path for the file containing the password. If the call is not made by a system user with Superuser/Administrator privileges, the location must be accessible by the system user making the call.

For example,

 isql -user sysdba -fet passfile server:employee

extracts the first line of from a file named passfile in the current working directory and loads it into the [PASSWORD] argument of the call.

The file name can be specified as stdin:

 isql -user sysdba -fet stdin server:employee

If stdin is the terminal, a prompt is presented —

 Enter password:

— requiring the operator to type in the password.

Tip: On POSIX, the operator will also be prompted if s/he specifies

 -fetch /dev/tty

This technique could be useful if, for example, you needed to restore from stdin (all one line):

 bunzip2 -c emp.fbk.bz2 | gbak -c stdin /db/new.fdb 
   -user sysdba -fetch /dev/tty

back to top of page

gsec

The following improvements have been added for gsec:

Mapping switch for Windows administrators

Alex Peshkov

Since v.2.1, Windows domain administrators have had full access to the user management functions. In v.2.5 they do not get these privileges automatically unless the SYSDBA has configured the security database to make it happen automatically.

In the Administrative features chapter is a detailed overview of the new system role RDB$ADMIN. There, you will find descriptions of the new ALTER ROLE syntax that can be used by the SYSDBA to enable or disable the automatic mapping of Windows administrators to the RDB$ADMIN role in databases, including the security database which they access when creating, altering and dropping users.

This automatic mapping can also be done in a gsec command-line call, using the new -mapping switch.

Mapping an OS administrator to the RDB$ADMIN role

The new -mapping switch is used to enable or disable the association of an operating system user with the RDB$ADMIN role in the security database. It takes one argument: either set to enable the association or drop to disable it. The syntax is:

 -mapping {set | drop}

Granting the RDB$ADMIN role to a Firebird user

The introduction of the RDB$ADMIN system role has made it possible to escalate the privileges of an ordinary user. However, it was (and still is) not possible any for any user, even SYSDBA, to attach directly to the security database and grant the required permissions for the user to manage other users. A parameter - GRANT ADMIN ROLE - was included in the new CREATE USER and ALTER USER statement syntaxes to enable SYSDBA, or another user that has already acquired the RDB$ADMIN role in the security database, to have the RDB$ADMIN role applied to an ordinary user "at arm's length", as it were.

The same can be achieved in gsec using the new switch -admin. It takes one argument: either YES (to grant the RDB$ADMIN´ role to the specified user in security2.fdb) or NO (to revoke it). The syntax is:

 -admin {YES | NO}

Command-line help for gsec

Claudio Valderrama

Tracker reference: CORE-756.

Parameter help has been implemented for gsec, accessible by using the -help or -? switches.

back to top of page

fbsvcmgr

Additions made to gsec and the Service Parameter Block (SPB) relating to the system role RDB$ADMIN are covered by the appropriate support in the fbsvcmgr utility.

• for gsec -mapping, two new tag items: isc_action_svc_set_mapping and isc_action_svc_drop_mapping.
• for gsec -admin: the new parameter isc_spb_sec_admin, of spb_long with either 0 as its value (meaning REVOKE ADMIN ROLE) or non-zero (meaning GRANT ADMIN ROLE).

For a full overview of the RDB$ADMIN role, refer to the topic New RDB$ADMIN system role in the Administrative features chapter.

back to top of page

gbak

Repair switches for malformed strings

Adriano dos Santos Fernandes

Tracker reference CORE-1831.

The gbak utility has two new restore switches intended to repair malformed UNICODE_FSS character data and metadata, respectively, when restoring the backup of an affected database.

Switch syntax

 -FIX_FSS_D(ATA) <charset> -- fix malformed UNICODE_FSS data
 -FIX_FSS_M(ETADATA) <charset> -- fix malformed UNICODE_FSS metadata

Hints with malformed string exceptions for restores:

(CORE-2754, A. dos Santos Fernandes)

When a restore fails with malformed string errors, gbak will supply a hint in verbose output, referring the user to the -FIX_FSS_METADATA and -FIX_FSS_DATA switches.

Preserve character set default collation

Adriano dos Santos Fernandes

Tracker reference CORE-789.

An improvement allows the current value of RDB$DEFAULT_COLLATE_NAME in the system table RDB$CHARACTER_SETS to survive the backup/restore cycle.

Improve insertion performance for restore

Adriano dos Santos Fernandes

Tracker reference CORE-3433.

(v.2.5.1) Improved performance in the records insertion phase of restore.

back to top of page

nBackup

New switches added

Four switches were added to nBackup:

 -FE <filename>   Fetch password from file
 -Z               Print version information
 -?               Help
 -D ON|OFF        Force direct I/O on or off

• -FE: Supports the feature allowing the authentication password to be fetched from a file. For details, see New -fetch_password switch in this chapter.
• -Z: Prints the version details of the nBackup executable.
• -?: Prints a terse list of usage instructions for the switches and options.
• -D: ON option enables direct input and output operations; OFF disables them. The default settings depend on the operating system and Firebird version, as follows:

Windows service-capable platforms

ON in all versions.

POSIX

OFF in 2.0-2.0.5, 2.1-2.1.2, 2.1.4, 2.5 and higher
ON in 2.1.3 and 2.0.6, provided O_DIRECT is available; otherwise OFF. POSIX_FADV_NOREUSE is also set, if available.

Note: Using -D ON has no effect if neither O_DIRECT nor POSIX_FADV_NOREUSE is available, although no error or warning will be raised.

Note: Support for the new -D switch is also included among changes to the Services API in this version. For details, see isc_spb_nbk_direct on|off in the chapter Changes to the Firebird API and ODS.

I/O resource load reduced on POSIX

An improvement has been done for POSIX versions to address a problem whereby the full backup tool of the nBackup incremental backup utility would hog I/O resources when backing up large databases, bringing production work to a standstill. Now, nBackup tries to read from the operating system cache before attempting to read from disk, thus reducing the I/O load substantially.

Note: The “cost” may be a 10 to 15 percent increase in the time taken to complete the full backup under high-load conditions.

Tracker reference CORE-2316.

back to top of page

isql

Some changes to the isql interactive query tool have been implemented.

SQLSTATE instead of SQLCODE

Claudio Valderrama

isql now returns the SQLSTATE completion code in diagnostics, instead of the now deprecated SQLCODE. For more information, see the topic Support for SQLSTATE completion codes in the chapter, Changes to the Firebird API and ODS.

Improvement for exponential number output

Claudio Valderrama

Tracker reference CORE-1171.

isql has always output different formatting of numbers on Windows and POSIX for two-digit exponents. The default behaviour of Microsoft and Intel compilers is to zero-pad the exponent to three digits regardless. For example,

 select cast ('-2.488355210669293e+39' as double precision)
   from rdb$database;

• On POSIX, the result is -2.488355210669293e+39
• On Windows, the result was -2.488355210669293e+039

The isql output has been modified so that the Windows output now conforms with that on other platforms.

SHOW COLLATIONS in isql help

Help for SHOW COLLATIONS has been added to the command-line help for isql. (Tracker reference CORE-2432, A. dos Santos Fernandes).

SET ROWCOUNT statement added

Mark O'Donohue

Added mainly to assist testers, this command enables a limit to be set on the number of rows a query returns to the interactive isql shell.

Example of use

The following isql statement will stop returning rows after the 10,000th row has been output:

 SQL>set rowcount 10000;

back to top of page

gpre (Precompiler)

Some updates

Stephen Boyd
Adriano dos Santos Fernandes

Tracker reference CORE-1527.

gpre now supports the IS NOT DISTINCT predicate and CASE/NULLIF/COALESCE/SUBSTRING functions, as well as the whole set of CURRENT_* context variables.

Deprecated features with future impact on utilities: In anticipation of the dropping of the intrinsic function isc_ddl from the Firebird 3 code base, certain features currently available in the gdef and gpre tools are deprecated - meaning that, whilst they may work in v.2.5, they will fail in Firebird 3. More details can be found in the Compatibility chapter.

gstat

Claudio Valderrama

Tracker reference CORE-1411.

The gstat statistics reporting utility now has -? and -help switches for requesting help about available switches and arguments.

back to top of page
<< International Language Support (INTL) | Firebird 2.5.3 Release Notes | Installation notes >>