| 1 |
README to instreg.exe and instsvc.exe |
| 2 |
------------------------------------- |
| 3 |
Authors: |
| 4 |
Original: Alex Peshkov (peshkoff at mail.ru) |
| 5 |
Revised by: Olivier Mascia (om at tipgroup.com) |
| 6 |
|
| 7 |
NOTE :: To solve any potential issues with long paths containing spaces |
| 8 |
or special (non ascii) characters, these tools no longer take the |
| 9 |
RootDirectory as a command-line argument. Both binaries must be installed |
| 10 |
in (or copied to) the /bin directory beneath your Firebird root directory. |
| 11 |
|
| 12 |
(Root directory == directory root where firebird.conf and security2.fdb are |
| 13 |
installed.) |
| 14 |
|
| 15 |
For example, if they are located in C:\FB20\bin, the root directory will |
| 16 |
be deduced as C:\FB20. |
| 17 |
|
| 18 |
============ |
| 19 |
INSTREG.EXE |
| 20 |
============ |
| 21 |
The purpose of this utility is to install the Registry keys for Firebird. |
| 22 |
Because its task is to deduce the RootDirectory path as the directory |
| 23 |
immediately above its own location and to write this to the Registry as an |
| 24 |
absolute path, instreg.exe must be installed in the /bin sub-directory of the |
| 25 |
Firebird root directory (see note above). |
| 26 |
|
| 27 |
The Registry key is *not* required for the engine to run; however, many |
| 28 |
third-party tools expect to read it in order to work. The key stored is |
| 29 |
HKLM\SOFTWARE\Firebird Project\Firebird Server\Instances |
| 30 |
and contains one string value: DefaultInstance. |
| 31 |
|
| 32 |
This 'DefaultInstance' string value contains the full path (backslash |
| 33 |
terminated) to the root directory of the installation. This setup is built |
| 34 |
so that management of named multi-instances of the server will be possible in |
| 35 |
a next version. Currently, the one and only instance receives the hard-coded |
| 36 |
name 'DefaultInstance'. There is nothing else stored in the registry. Any |
| 37 |
version or configuration information is to be found by third-parties tools |
| 38 |
in the relevant firebird.conf file. This file can be located thanks to the |
| 39 |
root path stored in the ...\Instances\DefaultInstance value. |
| 40 |
|
| 41 |
Usage: |
| 42 |
instreg i[nstall] |
| 43 |
r[emove] |
| 44 |
|
| 45 |
'-z' can be used with any other option, prints the Firebird software |
| 46 |
version as the first line of output. |
| 47 |
To get brief text help, just invoke instreg.exe with no arguments. |
| 48 |
|
| 49 |
============ |
| 50 |
INSTSVC.EXE |
| 51 |
============ |
| 52 |
Firebird provides a standard routine to manage the Firebird Service on |
| 53 |
WinNT/2000/XP platforms - instsvc.exe. |
| 54 |
|
| 55 |
Console messages |
| 56 |
---------------- |
| 57 |
Output of Windows error messages (if any) has been enhanced so that any |
| 58 |
required transliteration of ansi strings to the OEM charset of the console |
| 59 |
window is done. This means people using a non-English Windows will get |
| 60 |
Windows system error messages in their language with correct accents and |
| 61 |
so on. |
| 62 |
|
| 63 |
Security related features |
| 64 |
------------------------- |
| 65 |
The '-login' (or -l) option previously implemented has been extensively |
| 66 |
revised and enhanced. It can now be used to set up the service(s) to run |
| 67 |
under a specific user account (presumably with limited privileges on the |
| 68 |
system) instead of the default "LocalSystem". |
| 69 |
|
| 70 |
Usage |
| 71 |
------ |
| 72 |
instsvc i[nstall] [ -s[uperserver]* | -c[lassic] | -m[ultithreaded] ] |
| 73 |
[ -a[uto]* | -d[emand] ] |
| 74 |
[ -g[uardian] ] |
| 75 |
[ -l[ogin] username [password] ] |
| 76 |
[ -n[ame] instance ] |
| 77 |
[ -i[nteractive] ] |
| 78 |
|
| 79 |
sta[rt] [ -b[oostpriority] ] |
| 80 |
[ -n[ame] instance ] |
| 81 |
sto[p] [ -n[ame] instance ] |
| 82 |
q[uery] |
| 83 |
r[emove] [ -n[ame] instance ] |
| 84 |
|
| 85 |
This utility should be located and run from the 'bin' directory |
| 86 |
of your Firebird installation. |
| 87 |
|
| 88 |
'*' denotes the default values |
| 89 |
'-z' can be used with any other option, prints version |
| 90 |
'username' refers by default to a local account on this machine. |
| 91 |
Use the format 'domain\username' or 'server\username' if appropriate. |
| 92 |
|
| 93 |
|
| 94 |
Examples |
| 95 |
======== |
| 96 |
assuming Firebird is installed (copied to its installed location). |
| 97 |
|
| 98 |
Superserver and auto-startup are now the default. |
| 99 |
|
| 100 |
instsvc i OR instsvc install |
| 101 |
sets up a Superserver as a service |
| 102 |
in auto-startup (started at boot-up) mode |
| 103 |
under the default system identity, named "LocalSystem". |
| 104 |
|
| 105 |
instsvc i -g OR instsvc install -guardian |
| 106 |
as above, but starts the Guardian service first. |
| 107 |
|
| 108 |
The options "-demand" (-d) and "-classic" (-c) allow the defaults to be |
| 109 |
changed, so the classic server (instead of the superserver) can be |
| 110 |
configured as a service and either service can be configured to start |
| 111 |
on demand instead of starting at boot time. |
| 112 |
|
| 113 |
To remove the service(s) |
| 114 |
------------------------ |
| 115 |
Services must be stopped before being removed. |
| 116 |
This could be automated with 3 lines of code |
| 117 |
but it is better to leave it as is for safety. |
| 118 |
|
| 119 |
instsvc r OR instsvc remove |
| 120 |
removes the service definition. |
| 121 |
If Guardian was configured, both the guardian and |
| 122 |
server services will be removed. |
| 123 |
|
| 124 |
To start and stop the installed service(s) |
| 125 |
------------------------------------------ |
| 126 |
instsvc sta or instsvc start |
| 127 |
starts the server or Guardian + server, |
| 128 |
according to what was configured by the install command. |
| 129 |
instsvc sto or instsvc stop |
| 130 |
stops the server or Guardian + server, |
| 131 |
according to what was configured by the install command. |
| 132 |
|
| 133 |
To get a server condition report |
| 134 |
-------------------------------- |
| 135 |
This is a new command: |
| 136 |
|
| 137 |
instsvc q or instsvc query |
| 138 |
Prints a report of exactly *what* is configured and *how*, |
| 139 |
as well as whether the services are running or stopped. |
| 140 |
|
| 141 |
To use the secure login feature |
| 142 |
------------------------------- |
| 143 |
Option "-login" requires a username and a password: |
| 144 |
|
| 145 |
instsvc i -g -login user pass |
| 146 |
This would configure FB superserver as auto-start, with Guardian, |
| 147 |
to run under the identity "user" whose password is pass. |
| 148 |
|
| 149 |
* If the password is included, the password should not begin |
| 150 |
with '-'. |
| 151 |
|
| 152 |
* If the password is omitted from the command-line, instsvc |
| 153 |
will prompt for it. In that case, the password will be masked |
| 154 |
with '*' as it is typed. |
| 155 |
|
| 156 |
While configuring the services as above, instsvc automatically grants |
| 157 |
the Windows operating system privilege named "Log on as a Service" to |
| 158 |
the specified user. This is required, otherwise the service would not |
| 159 |
be allowed to start. Instsvc is silent about it unless it fails. |
| 160 |
|
| 161 |
To take care of the possibility that the user logging in via the -login |
| 162 |
switch might be an ordinary user with no administrator privileges on the |
| 163 |
machine, instsvc adjusts the default security descriptor of the service(s) |
| 164 |
so that this user can start/stop/query them. This is necessary to enable |
| 165 |
the Guardian (also running as this user) to start the FB server. The user |
| 166 |
will not be able to uninstall the service(s) nor change their |
| 167 |
configuration. |
| 168 |
|
| 169 |
NOTE |
| 170 |
---- |
| 171 |
Instsvc does not CREATE the "user" on the Windows machine. That would not |
| 172 |
be a good idea. The admin might want to create the user as part of the |
| 173 |
local machine or as part of a domain and instsvc has no particular need to |
| 174 |
usurp the admin's responsibility for creating users. |
| 175 |
|
| 176 |
The user needs to have read/write access to all databases and the |
| 177 |
firebird.log file. For security reasons, write access to firebird.conf |
| 178 |
and Firebird executables should NOT be given. |
| 179 |
|
| 180 |
On Windows NT/2K/XP it is common to include the domain or server prefix for a |
| 181 |
user defined on a domain or locally on another server. In the above examples, |
| 182 |
"user" might take the form of: |
| 183 |
DOMAIN\user or |
| 184 |
SERVER\user |
| 185 |
With no prefix, the user is implicitly a local user on the current machine. |
| 186 |
|
| 187 |
/* ends */ |