Debian Codegraph @

doc/README.instsvc

raw
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 */