summaryrefslogtreecommitdiffabout
path: root/doc/gsc.texi
blob: 87e1ce53152ca17eb82fb91fda5e4c2488414877 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
\input texinfo @c -*-texinfo-*-
@smallbook
@c %**start of header
@setfilename gsc.info
@settitle GSC 
@c %**end of header
@setchapternewpage odd

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@include version.texi
@include rendition.texi

@ifinfo
@direntry
* gsc: (gsc).       Gray's script collection
@end direntry
@end ifinfo

@copying
Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA

Copyright @copyright{} 2005 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end copying

@titlepage
@title GSC
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@page
@summarycontents
@page
@contents

@node Top, Intro, (dir), (dir)

@ifinfo
@chapter GSC
This edition of the @cite{GSC Manual}, last updated @value{UPDATED},
documents GSC Version @value{VERSION}.
@end ifinfo

@menu
* Intro::                  What is GSC?

* CVS Tools::              Various CVS-related Tools.
* Source Tree Utilities::  Batch Modifications to the Source Files.
* Root Utilities::         Various system-related utilities for use by
                           root.
* Sendmail mc Files::                           
* Startup Scripts::
* User Tools::             Just that.

* Reporting Bugs::         How to Report a Bug.

Appendices

* Copying This Manual::    The GNU Free Documentation License.
* Concept Index::          Index of Concepts.

Here are some other nodes which are really inferiors of the ones
already listed, mentioned here so you can get to them in one step:

@detailmenu
 --- The Detailed Node Listing ---

CVS Tools

* mksnapshot::      Create Snapshot Tarballs from the CVS or SVN repository.
* sv_logger::       Redirect stdin to syslog.
* Sync WWW::        Synchronize a Directory with a CVS Module Upon
                    Commit.

Sync WWW

* sv_sync_www_schedule:: Schedule a CVS to WWW Sync Job.
* sv_sync_www::          Synchronize CVS Directories with the
                         Corresponding WWW Directories.
* CVS Sync Example::     How to Set Up CVS synchronization framework.
* sv_www_loginfo::       Update CVSROOT/loginfo Files.                    

sv_sync_www

* Single job::
* Cron job::
* Invocation::

Source Tree Utilities

* fixnamespace::         Fix Global Namespace of a Project.
* fsf-move::             Update FSF Postal Mail Address in (L)GPL
                         Copyright Statements.

Root Utilities

* ckaliases::            Check MTA alias files.
* bind replication::     A Framework for Replicating Master @command{bind} Server.
* firewall::             M4 Wrappers For Setting Firewalls.
* session-cleanup::      Manage PHP Sessions.

firewall

* Primitives::        A set of primitives defined in @file{firewall.m4}

Startup Scripts

* rc.inet1::   	          A Replacement for Slackware @command{rc.inet1}.
* rc.autofs::	          Automounter Setup.
* rc.ntpd::	          @command{Ntpd} Setup.
* rc.local::	          Local Startup.
* rc.firewall::           Firewall Setup.
* rc.ipacct::             @command{ipacct} setup.
* rc.ppp::                Set up a @acronym{PPP} connection.
* rc.tagr::               @command{tagr} setup.

User Tools

* dict-setup::     Setup a set of @command{aspell} dictionaries.
* consoleconf::    Simple Tool for Console Font/Keyboard Mapping Switching.
* ppp::            A Framework for Setting Up a Dial-up Connection.

@end detailmenu
@end menu

@node Intro, CVS Tools, Top, Top
@chapter Introduction to GSC
@cindex @acronym{GSC} defined
     @acronym{GSC} stands for @dfn{Gray's Script Collection}. It is a
collection of various mostly unrelated tools and configuration files I
use in system administration and software development. The tools are
mainly for my own use, however I'd be glad if you find them useful
too. The package is distributed under GPL, for exact license terms and
conditions see file @file{COPYING} in the main distribution directory.

     This manual documents version @value{VERSION} of the package. It
is distributed under GFDL, @xref{Copying This Manual}.

@node CVS Tools, Source Tree Utilities, Intro, Top
@chapter CVS Tools

     This set of tools is designed to facilitate some tasks related to
@acronym{CVS} and Savane maintenance.

@menu
* mksnapshot::      Create Snapshot Tarballs from the CVS or SVN repository.
* sv_logger::       Redirect stdin to syslog.
* Sync WWW::        Synchronize a Directory with a CVS Module Upon
                    Commit.
@end menu

@node mksnapshot
@section mksnapshot
@pindex mksnapshot

@cindex snapshots, creating for CVS and SVN
@cindex CVS and SVN snapshots, creating
     This @command{mksnapshot} utility creates source tarballs from
modules in @acronym{CVS} and/or @acronym{SVN}
repositories. This is useful, for example, to create daily snapshots
from the repository.

     The program looks for modules in the @acronym{CVS} repository.
For each module found, it checks out first line of @file{ChangeLog}
file, and if it presents a date later than the one when the last
snapshot was made, it checks out the module into a temporary directory,
tars its contents and places the resulting archive into the
distribution directory.

     The resulting archive is named @file{@var{project}-@var{DATE}.tar.gz},
where @var{project} is the name of the module and @var{date} is latest
@file{ChangeLog} date in @samp{YYYY-MM-DD} format. In addition, a
symbolic link to the latest snapshot is created. The link is named
@file{@var{project}-latest.tar.gz}.

     The actual compression method, and the tarball suffix are
configurable (see the description of @code{COMPRESS} variable below).

     If the module is not found in the @acronym{CVS},
@command{mksnapshot} tries out the @acronym{SVN} repository, if it is
configured.  The repository last change date is checked using
@command{svn info} command, and if it is later than the date of the
last snapshot, the new snapshot is made, as described above.

     The program takes a single argument, a name of the configuration
file. This file should declare several environment variables that
control @command{mksnapshot} behavior.

@defvar CVSROOT
    This variable specifies the @acronym{CVS} root directory name.
@end defvar
    
@defvar SVNROOT
    This variable specifies the @acronym{SVN} root directory name.
@end defvar
    
@defvar WD
    A working directory for extracting repository data.
@end defvar
    
@defvar FTP
    Target directory where tarballs should be placed.
@end defvar

@defvar MAXSNAPSHOTS
    Maximum number of snapshots to keep for each project. This
variable is optional. It defaults to 3.
@end defvar
     
@defvar REPOSITORY
    Type of @acronym{CVS repository}. This variable is optional.
    
    Set @code{REPOSITORY=PLAIN} if you use classic ``plain'' @acronym{CVS}
repository, and @code{REPOSITORY=SAVANE}, if you use Savane-based
repository. Lower-case values are accepted as well. Default is
@samp{SAVANE}.

    @emph{Warning:} setting @code{REPOSITORY=PLAIN} works only with
@acronym{CVS} repositories.    
@end defvar

@defvar COMPRESS
Name of the compress program to use. Recognized values are
@samp{compress}, @samp{gzip} (default), and @samp{bzip2}.
Any other value is also accepted, provided that you also set the
@code{ZSUFFIX} variable (see below).
@end defvar

@defvar ZSUFFIX
Additional suffix for compressed tarballs (without leading
dot). Default values depend on the value of the @code{COMPRESS}
variable, as shown in the table below:

@multitable @columnfractions 0.6 0.4
@headitem COMPRESS value @tab Suffix
@item compress @tab Z
@item gzip @tab gz
@item bzip2 @tab bz2
@end multitable
@end defvar

@defvar VERBOSE
Set verbosity level. Allowed values are @samp{yes}, @samp{no}, or any
decimal number. The bigger the number, the more information is
displayed. The value of @samp{yes} is equivalent to @samp{1}, that of
@samp{no} is equivalent to @samp{0}. Default is @samp{no}.
@end defvar

    The behaviour of @command{mksnapshot} differs depending on the
type of repository used. For plain repositories, @command{mksnapshot}
processes all the modules in the repository, except
@code{CVSROOT}. Obviously, this approach works only for
@acronym{CVS} repositories.

    For Savane repositories, the program first gets the
list of user's groups, then for each group it looks up a module of
this name. When found, such module is processed as described above.
Thus, only those modules are selected, in which the current user
participates.

@node sv_logger
@section sv_logger
@pindex sv_logger

     This program reads its standard input line by line and sends each
line to the given @command{syslog} priority/facility. It could be used
to implement logging in shell scripts, especially those run with
non-root privileges.

     The program accepts two arguments:

@table @option
@item -t @var{tag}
     Specify the syslog @dfn{tag} to use. The tag will appear before
each logged line. The default tag is @samp{sv_logger}.

@item -p @var{facility}.@var{priority}
     Use specified @command{syslog} facility and priority. See
@code{syslog.conf(5)} for the list of valid falicity and priority
values. The default value is @code{user.notice}.
@end table
     
@node Sync WWW
@section Sync WWW
@cindex CVS synchronization
     The programs in this section form a framework for automatic
update of a directory upon @acronym{CVS} commit. This is useful,
for example, to keep a mirror of a module. Puszcza
(@url{http://puszcza.gnu.org.ua}) uses this for automatic update of
projects' home pages.

     This works as follows: suppose that each project keeps
publicly available data (@acronym{html} pages, etc) in directory
@file{/software/@var{project}}. These data are under @acronym{CVS} control in
directory @file{/webcvs/@var{project}}. Upon commit, @acronym{CVS}
server executes @file{CVSROOT/loginfo} which calls
@command{sv_sync_www_schedule}. This utility schedules an update
job. Another program, @command{sv_sync_www} is called as a
@command{cron} job. This program flushes all jobs scheduled so
far. For each project it changes to the project public directory and
performs @command{cvs update}  (well, actually it does much more than
that... @pxref{sv_sync_www}). 

     The following subsections describe each utility in detail.
     
@menu
* sv_sync_www_schedule:: Schedule a CVS to WWW Sync Job.
* sv_sync_www::          Synchronize CVS Directories with the
                         Corresponding WWW Directories.
* CVS Sync Example::     How to Set Up CVS synchronization framework.
* sv_www_loginfo::       Update CVSROOT/loginfo Files.                    
@end menu

@node sv_sync_www_schedule
@subsection sv_sync_www_schedule
@pindex sv_sync_www_schedule
@cindex Scheduling a CVS synchronization job
@cindex CVS synchronization job, scheduling
     The program @command{sv_sync_www_schedule} schedules a
@command{CVS} synchronization job for further execution. The jobs are
stored in directory @file{/var/spool/savane/}. This directory
must have sufficient permissions for @command{sv_sync_www_schedule} to
access it. Normally, this means adding each @acronym{CVS} user to a
common group, e.g. @samp{svusers} and setting directory access mode to
0775: 

@smallexample
@group
$ ls -ld /var/spool/savane
drwxrwxr-x    2 root     svusers        25 Aug 18 18:00 savane/
@end group
@end smallexample

@cindex @file{loginfo}, setting up for scheduled CVS synchronization
     The program takes three arguments: user name@footnote{not used
currently}, file name of the @acronym{CVS} repository, and the list of
files changed by the commit. The program is supposed to be invoked by
each commit. The proper way to do so is to add the following line to
the project's @file{CVSROOT/loginfo} file:

@smallexample
ALL      /bin/sv_sync_www_schedule $@{USER@} $@{CVSROOT@} %s
@end smallexample

     @command{sv_sync_www_schedule} logs errors via @command{syslog}
channel @code{local1.error}.

@node sv_sync_www
@subsection sv_sync_www
@pindex sv_sync_www
@UNREVISED{}
     The program @command{sv_sync_www} is the main engine for
@acronym{CVS} synchronization. It operates in two modes: in @dfn{single
job} mode it synchronizes a single @acronym{CVS} commit (called
@dfn{job}), in @dfn{cron job} mode it processes a set of accumulated
jobs at once.

     Whatever the mode is, the processing of a single job looks as
follows: the program determines @acronym{CVS} root directory,
subdirectory and files affected by the commit, changes to the
directory where the synchronization must be performed (a
@dfn{destination directory}, and runs @command{cvs update} with appropriate 
arguments. After update, @command{sv_sync_www} recursively searches
for files named @file{.symlinks} under the destination
directory. Each such file specifies the symbolic links that should be
created @emph{within a directory, where it resides}.

@cindex @file{.symlinks}
     In a @file{.symlinks} file any empty lines and lines starting
with @samp{#} or @samp{;} are ignored. Rest of lines must contain two
words: the name of the file to create the link from, and the name of
the link to be created. Thus, the following @command{.symlinks} file:

@smallexample
@group
# comment
gsc.html index.html
@end group
@end smallexample

@noindent
will create a link named @file{index.html}, pointing to the file
@file{gsc.html}.

     Notice that the linking is allowed only within or under the
directory containing @file{.symlinks} file. In particular,
@command{sv_sync_www} will refuse to create links whose names begin
with the directory separator or contain @samp{..}.

@menu
* Single job::
* Cron job::
* Invocation::
@end menu

@node Single job
@subsubsection Single job
@cindex @command{sv_sync_www}, single job mode

     Single job mode is the default mode for @command{sv_sync_www}. It
operates in this mode, unless @option{-s} command line option is
specified.

     It takes one or two command line arguments. A single command line
argument is parsed as a @code{%s} parameter in @file{loginfo}
invocation, i.e. it must consist of the project directory name and
the whitespace separated list of files, affected by the commit. The
project directory name can be absent, which is indicated by the
leading whitespace. The list of files can have two special forms:
@samp{- New directory} and @samp{- Imported sources}.

@cindex @command{sv_sync_www}, invoking from @file{loginfo}
@cindex @file{loginfo}, invoking @command{sv_sync_www}
@cindex @file{loginfo}, setting up for real time CVS synchronization
     In order to invoke @command{sv_sync_www_flush} on each commit,
the @file{loginfo} file must contain a line similar to the following:

@smallexample
@group
ALL  (date; cat; (sleep 2; /bin/sv_sync_www %s ) \
        &\ ) >> /var/log/sync_www.log 2>&1
@end group        
@end smallexample

@noindent
There are two notes on this example. First, programs like
@command{sv_sync_www} must be run in the background, otherwise they
will cause dead lock conditions due to the use of lock
files. Secondly, this example shows only the minimal invocation of
@command{sv_sync_www}. You will always need to pass it the commited
file name or names (see @samp{%s} above). However, depending on the
actual configuration you may need to pass it some configuration
options as well. 

@node Cron job
@subsubsection Cron job
@cindex @command{sv_sync_www}, cron job mode
@UNREVISED{}
     @command{Sv_sync_www} starts in cron job mode when it is given
@option{-s} command line argument. It takes a single optional
argument, specifying the @dfn{spool directory} to use (defaults to
@file{/var/spool/savane}. 

@node Invocation
@subsubsection Invocation
@UNREVISED{}
@cindex @command{sv_sync_www}, default settings
     First of all, @command{sv_sync_www} assumes some default
settings that you should know about. Namely, it supposes that both
@acronym{CVS} repository and update directory (hereinafter called
@dfn{WWW directory}) are located on the same server. Further, it
supposes that the former is called @file{/webcvs} and the latter is
called @file{/home/puszcza/software}. And, finally, it invokes
@command{cvs} binary using the following command line:

@smallexample
CVS_RSH=ssh cvs -q -z3
@end smallexample

     Of course, any of these defaults can be changed from the command
line.

@cindex @command{sv_sync_www}, command line options
@cindex @command{sv_sync_www}, specifying WWW directory
@cindex @option{-w}, @command{sv_sync_www} option
     To specify another @acronym{WWW} directory, use @option{-w} option.

@cindex @command{sv_sync_www}, specifying repository directory
@cindex @option{-R}, @command{sv_sync_www} option
     To specify a repository directory, use @option{-R}. The argument
to this option should be a directory name itself, without any access
method prefix. See below for a way to specify this.

     In particular, if you use @command{Savane}-like @acronym{CVS}
layout and wish to use immediate synchronization, your @file{loginfo}
would contain:
     
@smallexample
@group
ALL  (date; cat; (sleep 2; /bin/sv_sync_www -R $@{CVSROOT@} %s ) \
        &\ ) >> /var/log/sync_www.log 2>&1
@end group
@end smallexample

     The @command{sv_sync_www_flush} script passes this option by
default. 
     
@cindex @option{-H}, @command{sv_sync_www} option
@cindex @command{sv_sync_www}, specifying update server name 
     If the repository and @acronym{WWW} directory are located on different
servers, the IP address of host name of the server containing @acronym{WWW}
directory must be specified via @option{-H}.

@cindex @option{-r}, @command{sv_sync_www} option
@cindex @command{sv_sync_www}, specifying remote shell binary
@cindex @command{sv_sync_www}, accessing remote WWW server
     In this case @command{sv_sync_www} will invoke @command{cvs}
binary on the @acronym{WWW} server using @command{ssh} (more precisely:
@command{/usr/bin/ssh}). The name of the @command{ssh} binary can be
set using @option{-r} option.

@cindex @option{-m}, @command{sv_sync_www} option
@cindex @command{sv_sync_www}, specifying remote repository access method
     Further, invoked @command{cvs} will need to access @emph{remote}
@acronym{CVS} repository. The directory name of this repository can be
specified using @option{-R} option, described above. To specify access
method, use @option{-m} option. The argument to this option will be
prepended to the repository directory (either default one or the one
specified using @option{-R} option), so make sure you end it with a
colon.

@cindex @option{-c}, @command{sv_sync_www} option
@cindex @command{sv_sync_www}, specifying CVS command.
     By default, @command{sv_sync_www} will assume that
@command{cvs} should use @command{ssh} for accessing the remote server
(see the default @command{cvs} invocation above). If it is not the
case, you can use @option{-c} command line option. The @command{cvs}
commands will be appended to the supplied command verbatim. 

     Finally, please notice that using remote @acronym{WWW} server you
will have to set up an access from the @acronym{CVS} to @acronym{WWW}
and from the @acronym{WWW} to @acronym{CVS} without passwords (usually
this means setting up @command{ssh} for public keys authentication).

     To illustrate these concepts, suppose that the name of the remote
@acronym{WWW} server is @indicateurl{www.foo.org}, it should be accessed using
@command{rsh} (Note: @emph{do not use it} in real life. It is
unsecure), the repository itself should be accessed using
@samp{gserver} method, and all @acronym{CVS} interactions should use
maximal compression. Then, the command line for
@command{sv_sync_www} will be:

@smallexample
@group
sv_sync_www -H www.foo.org -m :gserver:cvs.foo.org: \
            -r rsh -c 'cvs -q -z9' -R $@{CVSROOT@} %s
@end group
@end smallexample

@cindex @option{-n}, @command{sv_sync_www} option
@cindex @command{sv_sync_www}, dry run
@cindex @option{-x}, @command{sv_sync_www} option
@cindex @command{sv_sync_www}, debugging
     When setting up unusual configurations, it is often useful to be
able to run @command{sv_sync_www} without actually changing
anything. This mode is called @dfn{dry run}, and it is turned on by
@option{-n} option. In dry run mode, @command{sv_sync_www} does not
change anything, instead it just prints what it would have
done. Additional debugging diagnostics can be enabled using
@option{-x} option.

@cindex @option{-h}, @command{sv_sync_www} option
@cindex @command{sv_sync_www}, obtaining help summary
     Finally, running @code{sv_sync_www -h} displays a short usage summary.

@node CVS Sync Example
@subsection Seting Up CVS synchronization framework.

@subsubheading Loginfo file
@smallexample
ALL  /usr/local/bin/sv_sync_www_schedule $@{USER@} $@{CVSROOT@} %s
@end smallexample

@subsubheading Crontab
@smallexample
@group
# Flush WWW synchronisation jobs, scheduled by sv_sync_www_schedule
# once an hour
0 */1 * * *     /usr/local/bin/sv_sync_www -s
@end group
@end smallexample

@node sv_www_loginfo
@subsection sv_www_loginfo
@pindex sv_www_loginfo
     The program @command{sv_www_loginfo} scans @file{loginfo} files
of all the projects in the repository and replace the default ones
(i.e. the ones whose contents is entirely commented out) with the
contents described in the previous subsection. This is to avoid
directly modfifying @command{Savane} sources and to achieve, at the
same time, the desired @acronym{WWW} synchronization
functionality. Once @command{Savane} is flexible enough to allow for
user-configurable @file{CVSROOT} contents, the need for this program
will go away.

     At the time of this writing, @command{sv_www_loginfo} is called
from @file{crontab} as follows:

@smallexample
@group
30 */2 * * * sv_groups --cron && \
             sv_users --cron && \
             sv_www_loginfo --cron
@end group
@end smallexample

     The program assumes the @acronym{CVS} repository under
@file{/webcvs}. It takes the following command line options:

@table @option
@item --cron
     Run as a cron job. All diagnostics is in this case reported via
@command{syslog} channel @code{local1.info}. Without this option it
goes directly to @code{stderr}.

@item --help
     Display short usage summary.
@end table

@node Source Tree Utilities, Root Utilities, CVS Tools, Top
@chapter Source Tree Utilities

     Programs described in this chapter perform a set of global
replacements on all the files within a project. The operation is being
performed in a separate directory, which is populated by @code{make
distdir} command. After the replacement, @code{make distcheck} is run
to ensure that the operation did not break integrity of the
project. If @code{distcheck} passes successfully, the resulting update
can be left in the temporary directory for further inspection,
archived in a @command{tar} archive, or propagated back to the
original project.

     Prerequisites for running these programs are:

@enumerate 1
@item Project must conform to GNU Coding Standards.
In particular, it must support @command{make distdir} and
@command{make distcheck} and these two goals must be built
successfully on the unmodified project.

@item The program must be run in the project top source directory
@end enumerate

     The usage synopsis is similar for both programs. The following
command line options are supported:

@cindex @command{fixnamespace}, command line options
@cindex @command{fsf-move}, command line options
@table @option
@item -k
@cindex @option{-k}, @command{fixnamespace} and @command{fsf-move} command line option
     Leave modified project in the temporary working directory. The
name of the working directory is formed as
@var{prefix}-@var{program}, where @var{prefix} is the base name of
the projects top source directory (unless overridden by @option{-p},
see below) and @var{program} is the name of the invoked program.

@item -r
@cindex @option{-r}, @command{fixnamespace} and @command{fsf-move} command line option
     Propagate the changed files to the original progect. This option
requires GNU @command{tar} version 1.15.1 or newer.

@item -t
@cindex @option{-t}, @command{fixnamespace} and @command{fsf-move} command line option
     Store modified project tree in tar archive named
@file{@var{prefix}-@var{program}.tar.gz}.
     
@item -p @var{prefix}
@cindex @option{-p}, @command{fixnamespace} and @command{fsf-move} command line option
     Specify name prefix for temporary working directory and tar
archive (see options @option{-k} and @option{-t}).

@item -h
     Display short usage summary.
@end table

@cindex @option{--configure}, @command{fixnamespace} and @command{fsf-move} command line option
     The command line options to @command{configure} can be given
using @option{--configure}. This option can be specified several
times, arguments of multiple @option{--configure} options are
concatenated in a whitespace separated list. The very first
@option{--configure} option should be preceeded by a double-dash:

@smallexample
-- --configure --with-prog
@end smallexample

      Any non-option arguments containing an equals sign, and any
non-option arguments beginning with double-dash (@samp{--}) are
considered to be additional @command{make} arguments and are passed to
@command{make} verbatim.

@menu
* fixnamespace::         Fix Global Namespace of a Project.
* fsf-move::             Update FSF Postal Mail Address in (L)GPL
                         Copyright Statements.
@end menu

@node fixnamespace
@section fixnamespace
@pindex fixnamespace
@cindex Fixing a project namespace.
     @command{Fixnamespace} utility replaces all global identifiers in
a project by prefixing them with a given string. This is useful for
creating a common namespace if a project contains a loadable library,
hence the name of the utility. Notice that only those symbols are
modified, that do not already begin with the prefix.

     @dfn{Global identifiers} are any functions, variables and
typedefs declared in the header files of the
project. To locate these, @command{fixnamespace} uses @dfn{tag files},
created by @command{etags} utility (@pxref{Tags,,Tags
Tables,emacs,GNU Emacs Manual}). Thus, to use @command{fixnamespace} you must
have Emacs version 21.3 or newer installed on your system.

@cindex @command{fixnamespace}, invocation
     The utility takes two or more arguments. First argument is the
prefix to be appended to all symbols. Rest of arguments specify the
header files where to look for global symbols. Only file names should
be given, without any directory prefixes.

@cindex @command{fixnamespace}, command line options.
     Apart from the command line options common for all source-tree
utilities, @command{fixnamespace} understands following option:

@table @option
@item -x @var{symbol}
     Exclude @var{symbol} from replacement. This option can be given
multiple times.
@end table

     Example of using this program:

@smallexample
fixnamespace -x scm_long2num mu_ message.h mailbox.h body.h list.h
@end smallexample

     Final notice: when too many header files are specified in the
command line, the number of created Lisp variable bindings can exceed
Emacs capacity; in this case @command{emacs} will signal an
error. To overcome this, increase value of @code{max-specpdl-size}
variable in @file{fixnamespace.el} near line 215.

@node fsf-move
@section fsf-move
@pindex fsf-move
     During my activity as a free software programmer, the Free
Software Foundation has twice changed its locations. Each such move
implied a change of postal mail address, and, consequently, a need for
updating each file in any free software project, since the standard
@acronym{GPL} or @acronym{LGPL} copyright header refers to it.

     Such a work can be very tedious for large projects, so when the
@acronym{FSF} has recently changed its location again, I decided to
automate the process once and for all. This is what @command{fsf-move}
is for. 

     The program does not take any special command line options or
arguments beside those described above (@pxref{Source Tree
Utilities}). Currently it is tuned to change postal mail address from

@quotation
59 Temple Place, Suite 330
Boston, MA
02110-1301 USA.
@end quotation

@noindent
to

@quotation
51 Franklin Street, Fifth Floor, 
Boston, MA
02110-1301 USA.
@end quotation

     Should @acronym{FSF} move again, you will have to change these defaults
by modifying @file{fsf-move}:177 and @file{fsf-move.awk}:21-22.

     The program implements a sophisticated search-and-replace
algorithm, if it knows a syntax of the language a file is written
in. The purpose of the algorithm is to allow for arbitrary splitting
of lines in the address and to preserve alignment and formatting of
comments. This algorithm is applied to files whose names match
following regexps:

@table @asis
@item *.[chyl]
     C sources;
@item *.m4|*.ac|*.at
     M4 sources;
@item *.sh
     Shell scripts;
@item *.awk
     AWK sources;
@item *.exp|*.tcl
     TCL sources;
@item *.am|Makefile.tmpl
     Automake sources;
@item *.el|*.scm*|*.lisp
     Various dialects of Lisp;
@end table

     PO files (@asis{*.po}), and their derivatives are ignored.

     The rest of files is processed using @dfn{fuzzy search}
algorithm, which is able to find the postal address in the majority of
cases, though not always. Such files should probably be inspected after
@command{fsf-move} finishes its work.

@node Root Utilities, Sendmail mc Files, Source Tree Utilities, Top
@chapter Root Utilities

     This chapter describes a set of utilities useful in system administration.

@menu
* ckaliases::            Check MTA alias files.
* bind replication::     A Framework for Replicating Master @command{bind} Server.
* firewall::             M4 Wrappers For Setting Firewalls.
* session-cleanup::      Manage PHP Sessions.
@end menu

@node ckaliases
@section ckaliases

@pindex ckaliases
     @command{Ckaliases} checks one or several
@command{sendmail}-style alias files for consistency. Following 
checks are performed:

@enumerate 1
@item Transitivity check
     This check discovers eventual circular dependencies.

@item Use of prohibited aliases
@end enumerate

     The program returns 0 if all checks pass successfully. Otherwise,
it diagnoses encountered problems and exits with error code 1.

@cindex @option{--files-from}, ckaliases option
@cindex @option{-f}, ckaliases option
@cindex ckaliases, @option{--files-from} command line option
@cindex ckaliases, @option{-f} command line option
     The program takes a list of alias files to be checked from its command
line. Additionally, the command line option @option{--files-from}
(@option{-f}) can be used to read the list of file names from a
plain-text file. Such a file must contain one file name per
line. Empty lines and lines beginning with @samp{#} are ignored. Any
file name that does not begin with a @samp{/} is searched in the same
directory where the list file resides. For example, assuming that the file
@file{/etc/mailman/LIST} contains:

@smallexample
mailman
mailman-test
@end smallexample

@noindent
then, the following invocation

@smallexample
$ ckaliases /etc/mail/aliases --files-from=/etc/mailman/LIST
@end smallexample

@noindent
instructs @command{ckaliases} to process files
@file{/etc/mail/aliases}, @file{/etc/mailman/mailman} and
@file{/etc/mailman/mailman-test}, in that order.

     In any case, if several alias files are supplied,
@command{ckaliases} treats them as parts of a single alias file.
     
@cindex @option{-w}, ckaliases option
@cindex ckaliases, @option{-w} command line option
     Before processing its input files, @command{ckaliases} reads
definitions of Sendmail @code{w} class from file
@file{/etc/mail/sendmail.cw}, or from a file specified using
@option{-w} command line option. For example, running

@smallexample
ckaliases -w /etc/mail/local-domains aliases
@end smallexample

@noindent
instructs @command{ckaliases} to use @file{/etc/mail/local-domains}.

@cindex @option{-r}, ckaliases option
@cindex @option{--restrict}, ckaliases option
@cindex ckaliases, @option{-r} command line option
@cindex ckaliases, @option{--restrict} command line option
@cindex @option{-u}, ckaliases option
@cindex @option{--unrestrict}, ckaliases option
@cindex ckaliases, @option{-u} command line option
@cindex ckaliases, @option{--unrestrict} command line option
     By default, the program allows any valid Sendmail constructions
in its input files. To restrict the input syntax to plain aliases only,
i.e. to prohibit use of pipes and file redirections, use
@option{--restrict} (@option{-r}) command line option. This option
affects any file names following it. To cances the restriction, use
@option{--unrestrict} (@option{-u}) option. For example: 

@smallexample
ckaliases aliases -r local -u global
@end smallexample

@noindent
This command restricts @file{local} to plain aliases only, while
allowing any aliases in files @file{aliases} and @file{global}.

@cindex @option{-v}, ckaliases option
@cindex @option{--verbose}, ckaliases option
@cindex ckaliases, @option{-v} command line option
@cindex ckaliases, @option{--verbose} command line option
@cindex @option{-d}, ckaliases option
@cindex @option{--debug}, ckaliases option
@cindex ckaliases, @option{-d} command line option
@cindex ckaliases, @option{--debug} command line option
     Two options are provided to help trace and debug program
actions. First, @option{--verbose} (@option{-v}) increases the verbosity
level. Secondly, @option{--debug} (@option{-d}) enables debugging
mode. This option takes a mandatory argument, a string specifying part
or parts of the program to debug. The characters valid in this string are:

@table @asis
@item l or L
     Enable lexical analyzer debugging information.
     
@item y or Y
     Enable debugging input grammar analyzer (parser).
@end table

     Any of these characters can be prefixed with @samp{-} (a dash),
to disable corresponding debugging feature, e.g. @code{-d y-l}.

@cindex @option{-h}, ckaliases option
@cindex @option{--help}, ckaliases option
@cindex ckaliases, @option{-h} command line option
@cindex ckaliases, @option{--help} command line option
     Finally, two usual informational options are available. The
@option{--help} (@option{-h}) displays a short usage summary, and
@option{--verbose} (@option{-v}) shows the program version number and
short reference to its copying conditions.
     
@subheading Example of @command{ckaliases} usage

@cindex @command{ckaliases}, example
     The following @file{/etc/mail/Makefile} rule constructs
@file{aliases} from several input files, provided that these are
valid alias files:

@smallexample
@group
aliases: .depend Aliases mailman/LISTS /com/mailer/aliases
         ckaliases Aliases -f mailman/LISTS -r /com/mailer/aliases
         @@(echo "# WARNING: DO NOT EDIT THIS FILE!!!"; \
         cat Aliases;\
         cat mailman/LISTS | \
         (cd mailman; \
          while read name; \
          do \
             case $$name in \
             \#*) ;; \
             *)   cat $$name;; \
             esac;\
          done);\
         cat /com/mailer/aliases) > aliases
@end group
@end smallexample
         
@node bind replication
@section bind replication
@UNREVISED{}

@node firewall
@section firewall
@cindex firewall
     The @file{firewall} subdirectory of the source tree contains an
@command{m4} wrapper over GNU/Linux @command{iptables} utility. The
basic idea behind it is to create a framework that could be used
without changes on any platform, no matter what the underlying
firewall implementation is. Currently it is implemented only for
@command{iptables}. The support for @acronym{BSD}-style @command{ipfw}
and, eventually, more will be added soon.

     The framework is based on a set of @command{m4} wrappers. From
the point of view of a final user, its usage is as follows. First,
the administrator creates a set of firewall rules using the primitives
supplied by @file{firewall.m4}. Then he processes @file{firewall.m4}
using @command{m4} and obtains a set of implementation-dependent firewall
rules that can be fed to the shell.

     You will probably not need to process @file{firewall.m4}
manually, we recommend to use @command{rc.firewall} instead
(@pxref{rc.firewall}). However, for the sake of completeness, here is
how it should be invoked:
     
@smallexample
m4 [-DSYSCONFDIR=@var{dir}] -DACTION=@var{action} firewall.m4
@end smallexample

@noindent
This command generates a set of implementation-dependent firewall
rules that can be fed to the shell.

     Its arguments are:

@defvar ACTION
     Specifies which set of commands @command{firewall.m4} is to
create. Possible values are:

@table @asis
@item status
     List actual firewall rules.
     
@item flush
     Flush the firewall rules.
     
@item @var{filename}
     Read in and process file @file{@var{filename}}.
@end table
@end defvar

     Optional variable @code{SYSCONFDIR} specifies a directory where
@file{rule.d} subdirectory is located (@pxref{rule.d}). It defaults to
@file{/etc/firewall}.

@menu
* Primitives::        A set of primitives defined in @file{firewall.m4}
@end menu

@node Primitives
@subsection Firewall Primitives
@UNREVISED{}

@deffn {Firewall Primitive} ACCEPT chain, srcip, srcport, dstip, dstport, proto, log
@end deffn

@deffn {Firewall Primitive} REJECT chain, srcip, srcport, dstip, dstport, proto, log
@end deffn

@deffn {Firewall Primitive} DENY chain, srcip, srcport, dstip, dstport, proto, log
@end deffn

@deffn {Firewall Primitive} LIST
@end deffn

@deffn {Firewall Primitive} port_setup rule ip
@anchor{rule.d}
@end deffn

@node session-cleanup
@section Manage PHP Sessions
@cindex session-cleanup
     The script @command{session-cleanup} provides flexible garbage
collection for @acronym{PHP} session files. It is designed first of
all for managing session files stored in a deep directory structrure
(i.e. when @code{session.save_path = @var{n};path} in @file{php.ini}),
for which the built-in @acronym{PHP} garbage collection is turned
off. Beside this, @command{session-cleanup} allows to set up different
@dfn{TTL} (@dfn{time to live}) intervals for different session files,
based on their contents.

@cindex @option{-c} command line option, @command{session-cleanup}
     The script should be started at regular intervals as a cron
job. Upon startup it obtains the value of @code{session.save_path}
variable from @file{/etc/apache/php.ini}. If your @file{php.ini} is
located elsewhere, specify its exact location using @option{-c}
command line option. Then @command{session-cleanup} scans the storage
directory and removes session files that were created more than
@acronym{TTL} days ago. The exact value of @acronym{TTL} is determined
using following rules:

@cindex Session @acronym{TTL} 
@cindex @command{session-cleanup}, setting session @acronym{TTL}
@enumerate 1
@item
@cindex @command{session-cleanup}, configuration file
@cindex configuration file for @command{session-cleanup}
If the command line contains a non-option argument, it is taken
as a name of @dfn{configuration file}. This file is scanned
for a line that matches the contents of the session file. If such a
line is found, it determines the @acronym{TTL} for this
session.

@item
@cindex @option{-t} command line option, @command{session-cleanup}
If @option{-t} is given in the command line, its argument
specifies @acronym{TTL}.

@item
Otherwise, default value of 3 days is used.
@end enumerate

     Configuration file has a simple line-oriented syntax. Blank lines
and lines that begin with a hash character (@samp{#}) are ignored. The
rest of lines is split into two fields. First field specifies a
@dfn{regular expression} to search for in the session file. Second
field gives the @acronym{TTL} value in days for files that match this
regular expression. The first matching line is used.

     A sample configuration file follows:

@smallexample     
# Regex                 TTL (days)

^gallery_session_.*     1
mprogh                  62
@end smallexample

@noindent
If a regular expression contains whitespace, use @command{shell}
escapes or quotes to protect it.

@subheading Syntax

@smallexample
session-cleanup @var{options} [@var{config-file}]
@end smallexample

@noindent
@var{options} are:

@table @option
@item -c @var{file}
     Use @var{file} instead of @file{/etc/apache/php.ini}.

@item -h
@cindex @option{-h} command line option, @command{session-cleanup}
     Display a short help summary.

@item -n
@cindex @option{-n} command line option, @command{session-cleanup}
     Dry run. Only display which files will be removed, do not
actually remove them. 

@item -t @var{ttl}
     Set default session time to live. @var{ttl} is measured in days.

@item -v
@cindex @option{-v} command line option, @command{session-cleanup}
     Verbose mode. Useful for debugging in conjunction with
@option{-n}.
@end table

@node Sendmail mc Files, Startup Scripts, Root Utilities, Top
@chapter Sendmail @file{mc} Files

     These are @command{sendmail} configurations for various machines.
To compile them you must have @command{sendmail} source tree
installed.

     By default, @command{configure} will look for @command{sendmail}
source directory in @file{/usr/src} and @file{/usr/local/src}. If it
finds several @command{sendmail} versions, it will use the one with
the greatest version number.

@cindex @option{--with-sendmail-cfdir}
     If the @command{sendmail} source directory is located elsewhere,
specify its exact location with
@option{--with-sendmail-cfdir=@var{dir}}, for example:

@smallexample
./configure --with-sendmail-cfdir=$HOME/sendmail-8.13.1
@end smallexample

@cindex @option{--with-sendmail-version}
     Otherwise, to force @command{configure} to pick up a specified
version of @command{sendmail}, use
@option{--with-sendmail-version=@var{version}} option.

     Once the package is configured, you can create all @file{.cf}
files using following command:

@smallexample
@group
cd mc
make cf
@end group
@end smallexample

     To create only @file{@var{file}.cf}, run @code{make
@file{@var{file}.cf}}.

@node Startup Scripts, User Tools, Sendmail mc Files, Top
@chapter Startup Scripts

     This chapter describes several startup files, designed mainly for
GNU/Linux. To use any of them, first read its description, then copy
it to the location where your startup scripts reside (@file{/etc/rc.d}
on @asis{Slackware}) and make sure it is executed at startup. Then
follow the script-specific recommendations set forth in the
corresponding section.

@menu
* rc.inet1::   	          A Replacement for Slackware @command{rc.inet1}.
* rc.autofs::	          Automounter Setup.
* rc.ntpd::	          @command{Ntpd} Setup.
* rc.local::	          Local Startup.
* rc.firewall::           Firewall Setup.
* rc.ipacct::             @command{ipacct} setup.
* rc.ppp::                Set up a @acronym{PPP} connection.
* rc.tagr::               @command{tagr} setup.
@end menu

@node rc.inet1
@section rc.inet1

@pindex rc.inet1
     The startup script @command{rc.inet1} sets up network
interfaces. It was thought as a replacement for @asis{Slackware}
startup script with the same name, which I find extremely
inconvenient.

     To use the script, copy it to the location where your startup
scripts reside (@file{/etc/rc.d} on @asis{Slackware}) and make sure it
is executed at startup. The script itself does not use any
configuration files. Instead, it consists of configurable and
immutable parts. Both parts are clearly separated with appropriate
comments.

     Configurable part contains a set of variable definitions. The
variables are:

@defvar if_list
     This variable contains a whitespace separated list of interface
names to be configured. For example:

@smallexample
if_list="lo eth0"
@end smallexample

@noindent
Each interface name must itself be a valid @command{shell} variable
name. Names of almost all existing interfaces meet this condition. The
common exception are ethernet aliases, which on GNU/Linux contain
colon. To list such an interface name, replace the colon with
underscore. For example to configure interfaces @code{lo}, @code{eth0}
and @code{eth0:0}, one would write:

@smallexample
if_list="lo eth0 eth0_0"
@end smallexample

     One more note: it is advisable to always keep @code{lo} in this
list.
@end defvar

@defvar if_@var{iface}
@cindex @code{if_@var{iface}}
     For each interface name @var{iface} in @code{if_list}, there must
be defined a variable named @code{if_@var{iface}}. The value of this
variable must be an @command{ifconfig} command line initializing given
interface. The name of the interface itself should be omitted from the
command line. Given the previous example, one might write:

@smallexample
@group
# Configure three interfaces
if_list="lo eth0 eth0_0"

# Set up loopback interface
if_lo="127.0.0.1"

# Set up eth0
if_eth0="inet 192.168.10.1 netmask 255.255.255.224\
         broadcast 192.168.10.31"

# Set up eth0:0
if_eth0_0="inet 192.168.10.2 netmask 255.255.255.224\
           broadcast 192.168.10.31"
@end group
@end smallexample
@end defvar

@defvar route_@var{iface}
     For each interface name @var{iface} in @code{if_list}, there can
be defined a variable @code{route_@var{iface}}. If it is defined, it
contains a @command{route} command line for setting up routing for
this interface. Completing our previous example, for loopback
interface one might write:

@smallexample
@group
if_lo"127.0.0.1"
route_lo="add -net 127.0.0.0 netmask 255.0.0.0 lo"
@end group
@end smallexample
@end defvar

@defvar default_gw
     This variable defines IP address of the default gateway.
@end defvar

@defvar static_routes
@cindex @code{route_@var{id}}, @command{rc.inet1} configuration variable
     The variable @code{static_routes} declares @dfn{route
identifiers} for each static route to be set up. A route identifier is
an arbitrary word consisting of alphanumeric characters and
underscores. For each identifier @var{id} in @code{static_routes}
there must be declared variable @code{route_@var{id}}, whose value is
@command{route} command line for setting up this route. For example:

@smallexample
@group
static_routes="1"
route_1="add -net 192.168.10.0 netmask 255.255.255.224 \
         gw 192.168.10.10 metric 216 reject"
@end group
@end smallexample
@end defvar

@FIXME{As other configuration scripts, this one should probably take a
command line argument @{@code{start}|@code{stop}|@code{status}@}. For
the time being it always behaves as if invoked with @code{start}}

@node rc.autofs
@section rc.autofs
@cindex @command{rc.autofs}
     The script @command{rc.autofs} controls GNU/Linux automounter
facility. It accepts a single mandatory command line argument:

@table @code
@item start
     Start automounter.

@item stop
     Stop automounter.
     
@item status
     List configured and active automounter instances and mount
points. Here is a sample output (long lines being split for readability):

@smallexample
@group
Configured Mount Points:
------------------------
/usr/sbin/automount --timeout=1 \
        /auto file /etc/automount/auto.misc

Active Mount Points:
--------------------
1040 /usr/sbin/automount --timeout=1 \
       /auto file /etc/automount/auto.misc
@end group
@end smallexample

@item reload
     Reload current configuration, restarting @command{automount}
daemon if necessary.

@item restart
     Unconditionally restart @command{automount} daemon.
@end table

     The script assumes following full file names:

@table @file
@item /usr/sbin/automount
@vindex DAEMON, @command{rc.autofs} configuration variable
     The name of the @command{automount} binary. Adjust @code{DAEMON}
variable if it is located elsewhere.

@item /etc/automount
@vindex CFGDIR, @command{rc.autofs} configuration variable
     Configuration directory. Adjust @code{CFGDIR} if you need another
name.

@item /etc/automount/master
@vindex CFGFILE, @command{rc.autofs} configuration variable
     The name of the master configuration file. Adjust @code{CFGFILE}
variable if you need another name.

@item /var/lock/subsys/autofs
@vindex LOCKFILE, @command{rc.autofs} configuration variable
     The name of the lock directory. Adjust @code{LOCKFILE} variable
if necessary.
@end table

@node rc.ntpd
@section rc.ntpd
@pindex rc.ntpd
     @command{Rc.ntpd} controls the @dfn{network time protocol}
daemon. It takes a single mandatory command line argument:

@table @code
@item start
@vindex TIMEOUT, @command{rc.ntpd} configuration variable          
@vindex MAXRETRY, @command{rc.ntpd} configuration variable
     Start @command{ntpd}. Before starting it the script
attempts to synchronize current date with the master servers by
running @command{ntpdate}. If @command{ntpdate} fails, the script
sleeps for a specified number of seconds and attempts to synchronize
again. Such attempts are tried several times while increasing
proportionally the initial delay between the attempts, so that the
delay after @var{n}th attempt is @var{n} times the initial one. Two
configuration variables are provided to control this behavior:
@code{MAXRETRY} sets the maximum number of attempts, @code{TIMEOUT}
sets the initial delay in seconds.
     If all attempts fail, @command{rc.ntpd} sends a mail to root and
exits without trying to launch @command{ntpd}. 

@item stop
     Stop @command{ntpd}.
     
@item status
     List running @command{ntpd} instances and display current
date/time difference between the local machine and its servers.
points. Here is a sample output (long lines being split for readability):

@smallexample
@group
Running processes:
------------------
1124 /usr/sbin/ntpd

Current date diff:
------------------
server 10.10.10.1, stratum 2, offset -0.008749, delay 0.13557
@end group
@end smallexample

@item reload
@itemx restart
     Restart @command{ntpd} daemon.
@end table

     The script assumes following full file names:

@table @file
@item /usr/sbin/ntpd
@vindex DAEMON, @command{rc.ntpd} configuration variable
     Name of the @command{ntpd} daemon. Kept in @code{DAEMON}
variable.

@item /etc/ntp.conf
@vindex CONFIG, @command{rc.ntpd} configuration variable     
     Main @command{ntpd} configuration file. Kept in @code{CONFIG}
variable. 

@end table

     The script searches @command{ntpdate}, @command{mail} and
@command{ps} binaries using usual path mechanism. You may need to
update @code{PATH} settings at the beginning of the script.

@node rc.local
@section rc.local
@pindex @command{rc.local}

The @command{rc.local} script manages @dfn{local services}.  For the
purposes of this script, we call each service a @dfn{component}.  It
is also supposed that the component management is handled by a script,
that takes a single word as its argument.  

A component name is used to locate its startup script.  If a component
name is a single word, @var{name}, then @command{rc.local} assumes the
script name is @file{/etc/rc.d/rc.@var{name}}.  Otherwise, if
@var{name} is a full path name, then it is used as a script name.

Additionally, if component name has the form
@samp{@var{user}@@@var{name}}, where @var{user} is a valid user name
and @var{name} is as described above, then the script will be executed
with the privileges of @var{user}.

The following table provides an example of valid component names along
with their description.

@table @asis
@item mailman
The script is named @file{/etc/rc.d/rc.mailman}.

@item postmaster@@mailman
The script is named @file{/etc/rc.d/rc.mailman} and is executed with
the privileges of the user @samp{postmaster}.

@item /usr/local/etc/rc.d/rc.mailman
The script is named @file{/usr/local/etc/rc.d/rc.mta}

@item postmaster@@/usr/local/etc/rc.d/rc.mailman
Same as above, but executed from the @samp{postmaster} account.
@end table

@menu
* local.conf::      Local Component Configuration File.
* rc.local usage::  Inocation and Command Line arguments.
@end menu

@node local.conf
@subsection local.conf file
@cindex @file{local.conf}
The configuration file @file{local.conf}, located in @file{/etc}
directory, contains the configuration for the @command{rc.local}.
The syntax is very simple:

@enumerate 1
@item Empty lines and comments are ignored.
@item Comments begin with @samp{#}.
@item The file consists of one or more @dfn{sections}.
@item Each section begins with @samp{[@var{name}]} on a line by
itself, and ends on the beginning of the next section, or end of file,
whichever occurs first.  The @var{name} above is the section name.
@item Each section contains a list of component names, each on a
separate line.
@end enumerate

The section named @samp{components} is mandatory.  It contains names
of all components managed by @command{rc.local}.  The components will
be started in the same order as listed in the section, and stopped in
the reverse order.  For example, given the following configuration
file:

@smallexample
[components]
mta
httpd
postmaster@@mailman
@end smallexample

@noindent
the order of startup is: @samp{mta}, @samp{httpd}, @samp{mailman}.
The order of shutdown is: @samp{mailman}, @samp{httpd}, @samp{mta}.

Additional sections may be provided to specify inter-component
dependency.  Such sections are named after a particular component and
contain a list of components that depend on that component.  For
example, consider this file: 

@smallexample
[components]
map
mysql
mta
httpd
postmaster@@mailman

[mta]
map
mysql
@end smallexample

The last section tells that @samp{mta} component depends on components
@samp{map} and @samp{mysql}.  If you run @samp{rc.local restart mta},
then the following sequence of commands will be performed:


@node rc.local usage
@subsection Inocation of @command{rc.local}.

@node rc.firewall
@section rc.firewall
@pindex rc.firewall
     This startup script sets firewall using @command{m4} firewall
wrappers (@pxref{firewall}). It tajes a single mandatory command line
argument:

@table @asis
@item start
@itemx restart
     Set up firewall.

@item stop
     Flush all firewall rules.

@item status
     List all installed firewall rules.

@item check
@itemx test
     Produce a list of shell commands that will be used to set up
firewall rules. Equivalent to @command{rc.firewall -d start}.
@end table

     Option @option{-d} can be given before the argument to make
@command{rc.firewall} produce a list of shell commands it would have
used to perform a given task. For example

@smallexample
rc.firewall -d start
@end smallexample

@noindent
prints commands that would be executed by @command{rc.firewall start}.

@vindex FWDIR
     The script searches for @command{m4} wrappers in
@file{/etc/firewall}. This location can be changed by setting
@code{FWDIR} environment variable.

@vindex START
     The list of firewall rules is expected to be located in
@file{@code{$FWDIR}/rules.m4}. This location can be changed by setting
@code{START} environment variable.
     
@node rc.ipacct
@section rc.ipacct
@pindex rc.ipacct
     This script controls the @command{ipacct} daemon
(@FIXME-pxref{ipacct}). It takes a single mandatory command line
argument indicating what action to take:

@table @asis
@item start
     Start the daemon.

@item stop
     Stop the daemon.

@item status
     Display @acronym{PID} of the current instance of
@command{ipacct}.

@item restart
     Unconditionally restart the daemon.

@item reload
@itemx reconfigure
     Tell @command{ipacct} to re-read its configuration file.
@end table

     The script searches for @command{ipacct} binary in the current
@code{PATH}. Two variables defined at the beginning of the script
control its behavior:

@defvar IFACE
     Interface where to install @command{ipacct}. Default is
@asis{eth0}.
@end defvar

@defvar PIDFILE
     Location of @command{ipacct} @acronym{pid} file. Default is 
@file{/var/run/ipacct-@code{IFACE}.pid}.
@end defvar

@node rc.ppp
@section rc.ppp
@pindex rc.ppp
     This script sets up a set of @acronym{PPP} connections at start
up. It reads configuration from the file @file{/etc/ppp.conf}. The
configurations is expressed as a set of shell variables.

@defvar ppp_list
     This variable contains a whitespace separated list of @dfn{identifiers}
for @acronym{PPP} connections. Each identifier is an arbitrary word,
such that it is a valid shell variable. For each identifier @var{id},
the configuration file must declare a shell variable
@code{ppp@var{id}_options}, specifying command line options for
@command{pppd}.
@end defvar

@defvar ppp@var{id}_options
@cindex @code{ppp@var{id}_options}, @command{rc.ppp} configuration variable
     This variable specifies command line options for connection
@var{id}.
@end defvar

     A sample @file{ppp.conf} file follows:

@smallexample
@group
ppp_list="0 1"
ppp0_options="modem passive nodetach defaultroute crtscts \
 lock 192.168.0.1:192.168.0.2 /dev/ttyS0 9600"
ppp1_options="modem lock 192.168.0.1:192.168.0.3 /dev/ttyS1 57600"
@end group
@end smallexample

@node rc.tagr
@section rc.tagr
@pindex rc.tagr
     @command{Rc.tagr} controls @command{tagr} daemon
(@FIXME-pxref{tagr}). It takes a single mandatory command line
argument indicating what action to take:

@table @asis
@item start
     Start the daemon.

@item stop
     Stop the daemon.

@item status
     Display @acronym{PID} of the current instance of
@command{tagr}.

@item restart
     Unconditionally restart the daemon.

@item reload
@itemx reconfigure
     Tell @command{tagr} to re-read its configuration file.
@end table

@vindex PIDFILE
@vindex PROGRAM
@vindex CMD
     The script searches for @command{tagr} binary in
@file{/usr/local/sbin/tagr} and for its @acronym{PID} file in
@file{/var/run/tagr.pid}. This can be changed by editing variables
@code{PROGRAM}, @code{PIDFILE} and @code{CMD} at the beginning of the
script.

@node User Tools, Reporting Bugs, Startup Scripts, Top
@chapter User Tools

@menu
* dict-setup::     Setup a set of @command{aspell} dictionaries.
* consoleconf::    Simple Tool for Console Font/Keyboard Mapping Switching.
* ppp::            A Framework for Setting Up a Dial-up Connection.
@end menu

@node dict-setup
@section dict-setup
@pindex dict-setup
     @command{Dict-setup} automates setting up a set of
@command{aspell} dictonaries (@pxref{Top,,Overview,aspell,GNU Aspell
Manual}). It takes a list of file names as its arguments. Each file
must contain a list of languages for which spell checking dictionaries
must be installed. The languages should be specified as ISO 639
language abbreviations, one per line. Empty lines and shell-style
comments are ignored.

     For each language, @command{dict-setup} downloads its latest
spell checking dictionary from
@url{ftp://ftp.gnu.org.ua/gnu/aspell/dict}, builds and installs it.

@cindex @option{-u} command line option, @command{dict-setup}.
     If you wish to use another @acronym{URL}, specify it via
@option{-u} command line option, for example

@smallexample
dict-setup -u ftp://ftp.gnu.org FILE
@end smallexample

@vindex SUF
     To save bandwidth, @command{dict-setup} looks for dictionaries
compressed via @command{bzip2} command. This can be altered by setting
@code{SUF} variable to the desired file suffix, e.g. @code{SUF=.tar.gz}.

@cindex @option{-c} command line option, @command{dict-setup}.
     By default, @command{dict-setup} installs the latest dictionary
version. If this behavior is not desired, you can select which
dictionary to install by invoking the program with @option{-c} option.

@cindex @command{lynx}
     When run with this option, @command{dict-setup} prints a list of
available dictionaries for each language and allows you to select one
for download (it uses @command{lynx} to display the list, so make sure
it is in your @code{PATH}). Use following commands to navigate through
the list:

@table @key
@item v
     View index file.
@item x
     Do not install dictionaries for this language. Proceed to the
next language.
@item q
     Abort installation immediately.
@item @var{number}
     Install @var{number}th dictionary from the list.
@end table     

@cindex @command{dict-setup} command line options
     Following is the complete list of @command{dict-setup} options:

@table @option
@item -c
@cindex @option{-c} command line option, @command{dict-setup}.
     Run in confirm mode: for each language, present the user with a
list of available dictionaries and allow him to select which one to
install.

@item -h
@cindex @option{-h} command line option, @command{dict-setup}.
     Print a short usage summary and exit.
     
@item -v
@cindex @option{-v} command line option, @command{dict-setup}.
     Verbosely list each action executed.
     
@item -u @var{url}
@cindex @option{-u} command line option, @command{dict-setup}.
     Use @var{url} instead of the default @url{ftp://ftp.gnu.org.ua/gnu/aspell/dict}.
@end table

@node consoleconf
@section consoleconf
@pindex consoleconf
     @command{Consoleconf} sets console encoding and input method, for
both text and X consoles. The program uses @command{kbd} package
(@url{ftp://ftp.win.tue.nl/pub/linux-local/utils/kbd/}).

     @command{Consoleconf} consists of the following parts:

@enumerate 1
@item @command{consoleconf} binary.
It is normally installed as @command{$prefix/consoleconf}.
@item Data directory with @dfn{language definition} files.
It is normally installed as @file{$datadir/consoleconf}.
@end enumerate

@cindex @command{consoleconf}, usage
@cindex @command{consoleconf}, invocation
     Usage of @command{consoleconf} is quite simple. Running:

@smallexample
consoleconf @var{lang}
@end smallexample

@noindent
sets up the console for language @var{lang}, i.e. it sets keyboard
map, optional screen map and screen font. Command line option
@option{-c} can be used to specify encoding. For example:

@smallexample
consoleconf -c latin1 no
@end smallexample

@cindex @command{consoleconf}, available languages
     The package is shipped with support for the following languages:

@table @asis
@item da
     Danish
     
@item es
     Spanish
     
@item el
     Greek
     
@item no
     Norwegian
     
@item pl
     Polish
     
@item ru
     Russian
     
@item uk
     Ukrainian
@end table

@cindex @command{consoleconf}, adding new language
     To add a new language, create its @dfn{language description file}
describing how to set up the console for this language. I suggest to
use two-letter language codes as per ISO 639. The file has a regular
@command{sh}(1) syntax. It should define following variables:

@defvar {Consoleconf variable} KEYMAP
     Specifies the name of the keymap to use. Keymaps are usually
stored in @file{/usr/share/kbd/keymaps/}, although the exact location
may vary.
@end defvar

@defvar {Consoleconf variable} FONT
     Specifies the name of console font file to use when in text console. Console
font files are usually located in @file{/usr/share/kbd/consolefonts/}, although the exact location
may vary.
@end defvar

@defvar {Consoleconf variable} X11
     @command{Setxkbmap} command line to use when under X11.
@end defvar

@defvar {Consoleconf variable} MOTD
     @dfn{Message of the day}. It is displayed after the console is
set up. If it starts with commercial at sign, it is taken as a name of
file whose contents is the message of the day. The file is looked up
in @file{$datadir/consoleconf/motd}.

     This variable is optional.
@end defvar

     For example, the following is the definition of Polish language:

@smallexample
@group
KEYMAP=pl.map
FONT="-m 8859-2 iso02.16.gz"
X11="-rules xfree86 -model pc102 -layout pl"
@end group
@end smallexample
     
@node ppp
@section ppp
@pindex start-ppp
@cindex @file{/etc/ppp/pppscript.m4}
     This sub-package provides a framework for setting up a dial-up
connection. At the core of it is @command{start-ppp}, a program which
actually installs a connection. Various configuration data are
supplied to it by several configuration files, normally located in
@file{/etc/ppp}. When run, @command{start-ppp} interprets the file
@file{/etc/ppp/pppscript.m4} to determine various configuration
settings for the modem. There is normally no need to edit this file,
as the actual configuration data are stored in two files it includes:
@file{/etc/ppp/modem} and @file{/etc/ppp/login}.

@cindex @file{/etc/ppp/modem}
     Modem configuration is kept in file @file{/etc/ppp/modem}. This
file should define the following variables.

@defvar MODEM_INITSTRING
     Initialization string for the modem.
@end defvar

@defvar MODEM_TIMEOUT
     Default modem timeout in seconds.
@end defvar

@defvar MODEM_DIALPREFIX
     Dial prefix, @samp{t} for tone dialing, @samp{p} for pulse dialing
@end defvar

@defvar AREA_CODE
     Optional area code.
@end defvar

@cindex @file{/etc/ppp/login}
     This file defines dial-up user credentials. These are kept in two
variables:

@defvar LOGIN
     Specifies user login name.
@end defvar

@defvar PASSWORD
     Specifies user password.
@end defvar

@cindex @file{/etc/ppp/numbers}
@cindex @file{./numbers}
     Finally, the list of numbers to dial is supplied by file
@file{/etc/ppp/numbers}. This file must contain one number per
line. Empty lines and shell-style comments are allowed. The numbers
from this file are tried in turn until dialing one of them succeeds or
the end of file is reached. By default, @command{start-ppp} first looks up
the file @file{numbers} in current working directory. If it is found,
it is read instead of @file{/etc/ppp/numbers}.
     
@node Reporting Bugs, Copying This Manual, User Tools, Top
@chapter How to Report a Bug

     As I said, this is not a package on its own. Rather @command{gsc}
is a collection of scripts for my own use. However, I will be pleased
if you will find it useful, and even more pleased if you will send me
your suggestions or bug reports. If you decide to do so, write to
@email{gray@@gnu.org.ua}. 

     As the purpose of bug reporting is to improve software, please be
sure to include maximum information when reporting a bug. The mimimum
information needed is:

@itemize
@item Topmost date from the @file{ChangeLog} file.
@item Conditions under which the bug appears.
@end itemize

@node Copying This Manual, Concept Index, Reporting Bugs, Top
@include fdl.texi

@node Concept Index,  , Copying This Manual, Top
@comment node-name,  next,  previous,  up
@unnumbered Concept Index

This is a general index of all issues discussed in this manual

@printindex cp

@bye

Local Variables:
compile-command: "makeinfo -DPROOF gsc.texi"
End:




Return to:

Send suggestions and report system problems to the System administrator.