firebird/firebird-mirror
firebird/firebird-mirror
8
0
Fork 1
mirror of https://github.com/FirebirdSQL/firebird.git synced 2025-01-22 18:43:02 +01:00
Code Issues

Sync with FB1.5 branch.

Browse Source
This commit is contained in:
epocman 2003-10-02 18:41:40 +00:00
parent f223899707
commit ccd62db02e
1 changed files with 189 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

247
doc/README.instsvc
View File

@ -1,79 +1,210 @@
README to instsvc.exe
----------------------
Author: Alex Peshkov (pes@insi.yaroslavl.ru)
README to instreg.exe and instsvc.exe
-------------------------------------
Authors:
Original: Alex Peshkov (pes at insi.yaroslavl.ru)
Revised by: Olivier Mascia (om at tipgroup.com)
Firebird provides a standard routine to manage the Firebird Service
on WinNT/2000/XP platforms - instsvc.exe.
NOTE :: To solve any potential issues with long paths containing spaces
or special (non ascii) characters, these tools no longer take the
RootDirectory as a command-line argument. Both binaries must be installed
in (or copied to) the /bin directory beneath your Firebird root directory.
NOTE Most of the instsvc switches are self-explanatory.
The only obscure one - the -z switch - causes
instsvc.exe to print the Firebird software version
as the first line of output.
(Root directory == directory root where firebird.conf and security.fdb are
installed.)
To install the Firebird service on your box:
For example, if they are located in C:\FB15\bin, the root directory will
be deduced as C:\FB15.
instsvc {install Firebird_directory [-auto | -demand] [-superserver | -classic]}
[-g[uardian]] [-l[ogin] username [password]] [-z]
============
INSTREG.EXE
============
The purpose of this utility is to install the Registry keys for Firebird.
Because its task is to deduce the RootDirectory path as the directory
immediately above its own location and to write this to the Registry as an
absolute path, instreg.exe must be installed in the /bin sub-directory of the
Firebird root directory (see note above).
To remove the service:
The Registry key is *not* required for the engine to run; however, many
third-party tools expect to read it in order to work. The key stored is
HKLM\SOFTWARE\FirebirdSQL\Firebird\Instances
and contains one string value: DefaultInstance.
instsvc {remove} [-g[uardian]] [-z]
This 'DefaultInstance' string value contains the full path (backslash
terminated) to the root directory of the installation. This setup is built
so that management of named multi-instances of the server will be possible in
a next version. Currently, the one and only instance receives the hard-coded
name 'DefaultInstance'. There is nothing else stored in the registry. Any
version or configuration information is to be found by third-parties tools
in the relevant firebird.conf file. This file can be located thanks to the
root path stored in the ...\Instances\DefaultInstance value.
To set the priority of the server process next time it is installed
(see also the reimplemented ProcessPriorityLevel parameter in
firebird.conf):
Usage:
instreg i[nstall]
r[emove]
instsvc {configure [-boostpriority | -regularpriority]} [-z]
'-z' can be used with any other option, prints the Firebird software
version as the first line of output.
To get brief text help, just invoke instreg.exe with no arguments.
To start the Firebird service with altered process priority:
============
INSTSVC.EXE
============
Firebird provides a standard routine to manage the Firebird Service on
WinNT/2000/XP platforms - instsvc.exe.
instsvc {start [-boostpriority | -regularpriority] } [-z]
Console messages
----------------
Output of Windows error messages (if any) has been enhanced so that any
required transliteration of ansi strings to the OEM charset of the console
window is done. This means people using a non-English Windows will get
Windows system error messages in their language with correct accents and
so on.
To stop the Firebird service:
Security related features
-------------------------
The '-login' (or -l) option previously implemented has been extensively
revised and enhanced. It can now be used to set up the service(s) to run
under a specific user account (presumably with limited privileges on the
system) instead of the default "LocalSystem".
instsvc {stop} [-z]
Usage
------
instsvc i[nstall] [ -s[uperserver]* | -c[lassic] ]
[ -a[uto]* | -d[emand] ]
[ -g[uardian] ]
[ -l[ogin] username [password] ]
To enhance Firebird security, the service management program
has been modified to accept a login switch, to optionally
pre-empt the LocalSystem user from being, by default, the user
under which the Firebird service logs in.
sta[rt] [ -b[oostpriority] ]
sto[p]
q[uery]
r[emove]
NOTE Regular user login is not compatible with the local access
protocol, which relies on SERVICE_INTERACTIVE_PROCESS mode
("Allow service to interact with Desktop"). For this reason,
unfortunately, the local access protocol remains a source of
vulnerability.
This utility should be located and run from the 'bin' directory
of your Firebird installation.
If the -[L] switch is not present, instsvc.exe proceeds as
before, logging in the service using the LocalSystem profile.
'*' denotes the default values
'-z' can be used with any other option, prints version
'username' refers by default to a local account on this machine.
Use the format 'domain\username' or 'server\username' if appropriate.
The switch [-Login username [password]] allows the Firebird
service to log in as a real user instead of the LocalSystem user.
When instsvc.exe detects this switch, it looks for two arguments,
username and password.
If a username is present, it proceeds to check the next string.
If the first character is not a '-' (minus sign), it interprets the
string as a password. Thus, the password should not begin with '-'.
If the username and password do not resolve to a valid domain
user, or one or both are missing, the usual NT built-in checking takes
over and any error will be due to a validation failure of the
domain\user string that is resolved from the input.
Examples
========
assuming Firebird is installed (copied to its installed location).
The user username needs to have privileges to log in as a service,
as well as read/write access to all databases and the firebird.log file.
For security reasons, write access to firebird.conf and Firebird
executables should NOT be given.
Superserver and auto-startup are now the default.
instsvc i OR instsvc install
sets up a Superserver as a service
in auto-startup (started at boot-up) mode
under the default system identity, named "LocalSystem".
instsvc i -g OR instsvc install -guardian
as above, but starts the Guardian service first.
The options "-demand" (-d) and "-classic" (-c) allow the defaults to be
changed, so the classic server (instead of the superserver) can be
configured as a service and either service can be configured to start
on demand instead of starting at boot time.
To remove the service(s)
------------------------
Services must be stopped before being removed.
This could be automated with 3 lines of code
but it is better to leave it as is for safety.
instsvc r OR instsvc remove
removes the service definition.
If Guardian was configured, both the guardian and
server services will be removed.
To start and stop the installed service(s)
------------------------------------------
instsvc sta or instsvc start
starts the server or Guardian + server,
according to what was configured by the install command.
instsvc sto or instsvc stop
stops the server or Guardian + server,
according to what was configured by the install command.
To get a server condition report
--------------------------------
This is a new command:
instsvc q or instsvc query
Prints a report of exactly *what* is configured and *how*,
as well as whether the services are running or stopped.
To use the secure login feature
-------------------------------
Option "-login" requires a username and a password:
instsvc i -g -login user pass
This would configure FB superserver as auto-start, with Guardian,
to run under the identity "user" whose password is pass.
Use of the -L switch disables the use of local protocol, so the
system administrator must choose between increased security and the
ability to use the local database access protocol. For production servers
that need to run in potentially aggressive environments, the -L switch is
strongly recommended.
* If the password is included, the password should not begin
with '-'.
* If the password is omitted from the command-line, instsvc
will prompt for it. In that case, the password will be masked
with '*' as it is typed.
NOTE A reworking of windows local access - a relic of its original
implementation back in Windows 3.11 - is overdue and is scheduled
for a release beyond Firebird 1.5. Amongst other changes, it
will be made compatible with the -l[ogin] switch in instsvc.exe.
While configuring the services as above, instsvc automatically grants
the Windows operating system privilege named "Log on as a Service" to
the specified user. This is required, otherwise the service would not
be allowed to start. Instsvc is silent about it unless it fails.
To take care of the possibility that the user logging in via the -login
switch might be an ordinary user with no administrator privileges on the
machine, instsvc adjusts the default security descriptor of the service(s)
so that this user can start/stop/query them. This is necessary to enable
the Guardian (also running as this user) to start the FB server. The user
will not be able to uninstall the service(s) nor change their
configuration.
NOTE
----
Instsvc does not CREATE the "user" on the Windows machine. That would not
be a good idea. The admin might want to create the user as part of the
local machine or as part of a domain and instsvc has no particular need to
usurp the admin's responsibility for creating users.
The user needs to have read/write access to all databases and the
firebird.log file. For security reasons, write access to firebird.conf
and Firebird executables should NOT be given.
On Windows NT/2K/XP it is common to include the domain or server prefix for a
user defined on a domain or locally on another server. In the above examples,
"user" might take the form of:
DOMAIN\user or
SERVER\user
With no prefix, the user is implicitly a local user on the current machine.
Instsvc and the "local" client/server protocol
==============================================
When Firebird is configured to run under a specific user--which is
recommended for servers on wide networks--the "local" protocol is
unavailable.
NOTE Regular user login is not compatible with the local access
protocol. Local protocol needs the server and the client to
interact by way of an emulated network layer using Windows messages.
A service running under a specific user account runs in its own,
isolated, virtual desktop environment and those messages cannot be
delivered. It is necessary for local clients to connect using TCP/IP
local loopback protocol (localhost server).
This is not a bug but, rather, implements a function of Windows
NT/2K/XP design that has some shortcomings. In future releases,
local protocol will be re-implemented, using proper inter-process
communication mechanisms.
When Firebird is configured without a specific user (i.e. LocalSystem
user in SERVICE_INTERACTIVE_PROCESS mode, "Allow service to interact
with Desktop"), both TCP/IP local loopback and "local" protocols are
available.
/* ends */