ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/svn/vendor/ircservices-5.1.24/docs/upgrade.html
Revision: 3389
Committed: Fri Apr 25 14:12:15 2014 UTC (9 years, 10 months ago) by michael
Content type: text/html
File size: 14944 byte(s)
Log Message:
- Imported ircservices-5.1.24

File Contents

# Content
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv=Content-Type content="text/html; charset=iso-8859-1">
5 <title>IRC Services - Important information about upgrading</title>
6 </head>
7
8 <body>
9 <a name=top></a>
10 <h1 align=center>IRC Services Manual</h1>
11
12 <h2 align=center>Important information for users upgrading from previous
13 versions of Services</h2>
14
15 <p><a href="#4.5">Upgrading from version 4.5 and earlier to 5.0</a>
16 <br><a href="#5.0">Upgrading from version 5.0 to 5.1</a>
17
18 <p>Note that information for later versions is applicable to earlier
19 versions as well, so please read through to the end of the document.
20
21 <p align=right><font size=-1><a href=index.html>Table of Contents</a></font>
22
23 <p><hr>
24
25 <a name=4.5></a>
26 <h2 align=center>Upgrading from version 4.5 and earlier</h2>
27
28 <a name=4.5-1></a>
29 <h3 align=center>1. Executable and configuration files</h3>
30
31 <p>In previous versions of Services, the main executable file (program
32 file) was called "<tt>services</tt>"; in version 5.0 it has been renamed to
33 "<tt>ircservices</tt>" to match the package name. Once you are satisfied
34 that you don't need the old <tt>services</tt> executable file, you should
35 delete it (<tt>make install</tt> will leave it alone).
36
37 <p>Also, previous versions of Services (since 4.1.0) used a file called
38 "<tt>services.conf</tt>" to control various aspects of the behavior of
39 Services. Services 5.0 also uses such a file, but it has been renamed to
40 "<tt>ircservices.conf</tt>" and its format has changed from previous
41 versions. In particular, many of the options from previous versions are
42 now module options, and must be placed in a separate file called
43 "<tt>modules.conf</tt>". Please see the manual, and the
44 <tt>example-ircservices.conf</tt> and <tt>example-modules.conf</tt> files
45 in the data directory, for details.
46
47 <p align=center><hr width="50%">
48
49 <a name=4.5-2></a>
50 <h3 align=center>2. Running the <tt>configure</tt> script</h3>
51
52 <p>The <tt>configure</tt> script has been redesigned to require as little
53 input as possible; many of the options that previously required user input
54 during the configuration process have been moved to the
55 <tt>ircservices.conf</tt> file, and the script can now be completely
56 automated if you provide the <tt>-prefix</tt> option or both of the
57 <tt>-bindest</tt> and <tt>-datdest</tt> options to specify the pathnames
58 for installation. Run <tt>configure</tt> with the <tt>-help</tt> option
59 for details on available command-line options.
60
61 <p>The <tt>configure</tt> script also now accepts all options in the GNU
62 long-option (two leading hyphens) style, so if you are used to the GNU
63 autoconf-style <tt>configure</tt>, you can now type <tt>./configure
64 --prefix=/usr</tt> (for example) to get the same effect with Services.
65
66 <p align=center><hr width="50%">
67
68 <a name=4.5-3></a>
69 <h3 align=center>3. <tt>listnicks</tt> and <tt>listchans</tt></h3>
70
71 <p>Earlier versions of Services provided two additional programs,
72 "<tt>listnicks</tt>" and "<tt>listchans</tt>", to show nickname and
73 channel data from the command line. These programs have been removed in
74 version 5.0 in favor of the new HTTP interface; the <tt>httpd/dbaccess</tt>
75 module provides the same functionality and much, much more. (It is still
76 possible to retrieve data from the command line as well, using the
77 <tt>-export</tt> option; see <a href="5.html#1">section 5-1</a> for
78 details.)
79
80 <p align=center><hr width="50%">
81
82 <a name=4.5-4></a>
83 <h3 align=center>4. Encrypted passwords</h3>
84
85 <p>Unlike previous versions of Services, encryption is no longer an
86 "on/off" setting; instead, encryption is enabled by specifying an
87 encryption module in <tt>ircservices.conf</tt>. See the manual
88 (<a href="3.html#7">section 3-7</a>) for details.
89
90 <p>If you are upgrading from version 4.4.x or earlier, and you use
91 MD5-encrypted passwords, <b>your passwords will no longer work</b> due to a
92 bug in those versions of Services. Support is available in version 4.5 for
93 reading the broken passwords and allowing them to be reset; if you want to
94 give users a chance to change their passwords, you should first upgrade to
95 the most recent 4.5.x release, then when most or all of the users have
96 reset their passwords, upgrade to version 5.0. For details, see the What's
97 New notes for version 4.5.
98
99 <p align=center><hr width="50%">
100
101 <a name=4.5-5></a>
102 <h3 align=center>5. Using the <tt>mail-auth</tt> module with existing
103 databases</h3>
104
105 <p>The <tt>mail-auth</tt> module is a new feature in version 5.0 which
106 allows E-mail addresses to be checked for validity. When enabled, all new
107 nickname registrations and E-mail address changes will require the user to
108 verify that the address provided is valid, by entering an authentication
109 code mailed by Services to the address. However, if you are upgrading from
110 an earlier version of Services, some users may already have entered invalid
111 E-mail addresses for their nicknames.
112
113 <p>To correct this situation, the command-line option
114 "<tt>-clear-nick-email</tt>" can be given (note that this option is only
115 valid if NickServ is enabled). When this option is used, Services will
116 clear the E-mail address associated with all registered nicknames; all
117 users will then be required to enter their E-mail address again and verify
118 it with an authentication code before being allowed to identify for their
119 nicknames.
120
121 <p>If you intend to use the <tt>mail-auth</tt> module, it is recommended
122 that you use this option once when starting up Services 5.0 for the first
123 time. This option only needs to be specified once to take effect.
124
125 <p align=center><hr width="50%">
126
127 <a name=4.5-6></a>
128 <h3 align=center>6. Nickname linking system changes</h3>
129
130 <p>The nickname linking system used in Services 5.0 is different from that
131 used in previous versions. Rather than a multiple-level "tree" of linked
132 nicknames, nicknames are now organized into groups, and the <tt>LINK</tt>
133 and <tt>UNLINK</tt> commands add nicknames to or remove nicknames from this
134 group. Functionally, there is little difference between this system and
135 using only one level of links in the previous system. However, the
136 <tt>LINK</tt> and <tt>UNLINK</tt> commands work in the opposite direction
137 from version 4.x, taking a nickname parameter and adding or removing that
138 nickname (for example, "<tt>LINK OtherNick</tt>"), and nicknames to be
139 linked must be <i>unregistered</i> nicknames, which is also a change from
140 version 4.x; make sure your users are aware of these changes.
141
142 <p>Related to these changes, it is also important to note that the
143 behavior of the NickServ <tt>UNLINK</tt> and <tt>DROP</tt> commands has
144 changed with respect to de-registration of nicknames; in particular, <b>the
145 <tt>DROP</tt> command will now drop <i>all</i> linked nicknames!</b> The
146 syntax for the <tt>DROP</tt> command has changed as well, requiring a
147 password to confirm the action, and the help message includes a warning,
148 but be aware that users may simply append their password to the command
149 without checking the help message, resulting in the unintended
150 de-registration of all of the user's nicks. The <tt>UNLINK</tt> command
151 should be used to cancel single nicknames out of a group of links (a
152 nickname which is unlinked is deregistered as well, similar to
153 <tt>UNLINK</tt> followed by <tt>DROP</tt> in version 4.x).
154
155 <p align=center><hr width="50%">
156
157 <a name=4.5-7></a>
158 <h3 align=center>7. Memo expiration</h3>
159
160 <p>Version 5.0 of Services provides the ability to automatically delete
161 (expire) memos after a certain period of time. Since this feature was not
162 present in previous versions and users may have important information saved
163 in memos, Services will not expire any memos which were sent before
164 upgrading to version 5.0; thus, it is safe to enable memo expiration without
165 having to warn users about loss of saved memos or taking other preventative
166 measures. (However, it would be prudent to inform users that any future
167 memos will expire after a certain period of time, if you choose to enable
168 memo expiration.)
169
170 <p align=center><hr width="50%">
171
172 <a name=4.5-8></a>
173 <h3 align=center>8. Channel access levels</h3>
174
175 <p>Channel access levels have been rescaled in this version of Services to
176 make better use of the available range of values; instead of a range of
177 -9999 through 9999 where only values -2 through 10 are used, the range has
178 been reduced to -999 through 999, and default levels now range from -100 to
179 100 (all defaults have been increased by a factor of 10, with the exception
180 of <tt>AUTODEOP</tt> and <tt>NOJOIN</tt>, which are no longer changeable in
181 version 5.0 but are fixed internally at -1 and -100 respectively). Level
182 values from version 4.x databases will be properly converted to use the new
183 range, so that all users will still have the same privileges as they did in
184 previous versions. However, be aware that in some cases involving two
185 users with levels outside the range -50 through 50 in version 4.x, if the
186 levels are different but close (<i>e.g.</i> 1001 and 1002), then the users
187 will have the same access level in version 5.0. The exact conversion
188 function is stepwise linear, as follows (negative levels are converted to
189 the negative of the conversion of the absolute value of the level):
190
191 <div align=center><table border=0>
192 <tr><th colspan=3>&nbsp;&nbsp;Old&nbsp;level&nbsp;(<i>o</i>)&nbsp;
193 <th colspan=3>&nbsp;New&nbsp;level&nbsp;(<i>n</i>)&nbsp;&nbsp;
194 <th>Conversion function
195 <tr><td align=right>0<td>. . .<td>25
196 <td align=right>0<td>. . .<td>250
197 <td><i>n</i> = 10<i>o</i>
198 <tr><td align=right>25<td>. . .<td>50
199 <td align=right>250<td>. . .<td>300
200 <td><i>n</i> = 2<i>o</i> + 200
201 <tr><td align=right>50<td>. . .<td>100
202 <td align=right>300<td>. . .<td>320
203 <td><i>n</i> = 2<i>o</i>/5 + 280
204 <tr><td align=right>100<td>. . .<td>1000
205 <td align=right>320<td>. . .<td>500
206 <td><i>n</i> = <i>o</i>/5 + 300
207 <tr><td align=right>1000<td>. . .<td>2000
208 <td align=right>500<td>. . .<td>600
209 <td><i>n</i> = <i>o</i>/10 + 400
210 <tr><td align=right>&nbsp;&nbsp;2000<td>. . .<td>9999&nbsp;
211 <td align=right>&nbsp;&nbsp;600<td>. . .<td>999&nbsp;&nbsp;&nbsp;
212 <td><i>n</i> = <i>o</i>/20 + 500
213 </table></div>
214
215 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
216
217 <p><hr>
218
219 <a name=5.0></a>
220 <h2 align=center>Upgrading from version 5.0</h2>
221
222 <a name=5.0-1></a>
223 <h3 align=center>1. Switching to the new database format</h3>
224
225 <p>A new, more robust database file format has been developed for version
226 5.1 which is incompatible with the format used in earlier versions. To
227 switch your databases to this format, ensure that the
228 <tt>misc/xml-export</tt> and <tt>misc/xml-import</tt> modules are loaded by
229 your <tt>ircservices.conf</tt>, and:
230 <ol>
231 <li>Shut down Services.
232 <li>Export your databases to an XML file using the command:
233 <tt>ircservices&nbsp;-export=<i>database.xml</i></tt> (any filename can
234 be used).
235 <li>Edit your <tt>ircservices.conf</tt> file and change the line reading
236 <br><tt>&nbsp;&nbsp;&nbsp;&nbsp;LoadModule&nbsp;database/version4</tt>
237 <br>to
238 <br><tt>&nbsp;&nbsp;&nbsp;&nbsp;LoadModule&nbsp;database/<b>standard</b></tt>
239 <br>Also enable the <tt>misc/xml-import</tt> module if it is commented
240 out.
241 <li>Import the XML data from step 2 into the new database format using the
242 command: <tt>ircservices&nbsp;-import=<i>database.xml</i></tt>
243 <li>Start up Services.
244 </ol>
245
246 <p>Note that switching to the new database format is not required; you can
247 continue to use your 5.0 databases by leaving the <tt>LoadModule
248 database/version4</tt> configuration line alone. However, the new database
249 format allows you to recover more data even if the database files get
250 corrupted, so its use is recommended. (It is also possible to switch back
251 to the old format from the new one in a similar manner, though all
252 5.1-specific data will be lost if the databases are used in an older
253 version of Services.)
254
255
256 <p align=center><hr width="50%">
257
258 <a name=5.0-2></a>
259 <h3 align=center>2. Channel memos</h3>
260
261 <p>Version 5.1 includes a redesigned channel memo system which distributes
262 channel memos to users of the channel (based on the channel access list)
263 rather than storing the memos with the channel. As a result of this
264 change, all stored channel memos will be deleted when starting up version
265 5.1. Users should be instructed to save any needed information before the
266 upgrade.
267
268 <p align=center><hr width="50%">
269
270 <a name=5.0-3></a>
271 <h3 align=center>3. Encryption handling</h3>
272
273 <p>Version 5.1 allows passwords encrypted with different ciphers (or not
274 encrypted at all) to coexist in the same database, by keeping track of
275 what cipher was used to encrypt the password; this allows for enabling or
276 disabling encryption, or changing the encryption type used, without
277 concerns of old passwords becoming unusable.
278
279 <p>However, since this ability was not present in version 5.0 and earlier,
280 Services has no way to know what encryption type was used in databases from
281 those versions, and simply defaults to the cipher given in the
282 <a href="a.html#EncryptionType"><tt>EncryptionType</tt></a> directive in
283 <tt>ircservices.conf</tt> for all passwords. Therefore, if you continue to
284 use the <tt>database/version4</tt> database module in version 5.1, you must
285 ensure that <tt>EncryptionType</tt> is set correctly when you first load
286 the data; once you have saved the databases using version 5.1, such as with
287 the OperServ <tt>UPDATE</tt> or <tt>SHUTDOWN</tt> commands, you can change
288 <tt>EncryptionType</tt> freely.
289
290 <p>This also applies, of course, to converting databases from 5.0 to the
291 new <tt>database/standard</tt> module format; be certain that you do not
292 change <tt>EncryptionType</tt> until after you have exported the databases
293 to an XML file.
294
295 <p align=center><hr width="50%">
296
297 <a name=5.0-4></a>
298 <h3 align=center>4. NickServ/ChanServ <tt>SENDPASS</tt></h3>
299
300 <p>The NickServ and ChanServ <tt>SENDPASS</tt> commands have been removed
301 in favor of the new NickServ <tt>REAUTH</tt> command, and the corresponding
302 modules (<tt>nickserv/sendpass</tt> and <tt>chanserv/sendpass</tt>) have
303 been deleted. Make certain to remove these modules from your
304 <tt>ircservices.conf</tt> file before starting Services 5.1.
305
306 <p align=center><hr width="50%">
307
308 <a name=5.0-5></a>
309 <h3 align=center>5. NickServ <tt>SET</tt> and <tt>UNSET</tt></h3>
310
311 <p>Services administrators should be aware that the NickServ <tt>SET</tt>
312 and <tt>UNSET</tt> commands now require a "<tt>!</tt>" before the nickname;
313 for example, instead of
314 <br><tt>&nbsp;&nbsp;&nbsp;&nbsp;/msg NickServ SET nick NOEXPIRE ON</tt>
315 <br>type
316 <br><tt>&nbsp;&nbsp;&nbsp;&nbsp;/msg NickServ SET <b>!nick</b> NOEXPIRE ON</tt>
317 <br>This is to avoid ambiguity where the nickname is the same as an option
318 name.
319
320 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
321
322 <p><hr>
323
324 <p align=right><font size=-1><a href=index.html>Table of Contents</a> |
325 <a href="#top">Top</a></font>
326
327 </body>
328 </html>