-
Notifications
You must be signed in to change notification settings - Fork 1
/
sys.8
1293 lines (1292 loc) · 35.4 KB
/
sys.8
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
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SYS" 8 "2023" "" "Utilities"
.SH NAME
sys \- a rule-based command-line tool for executing a command as another user
.\" ###################################################################
.\" Copyright 2022, Pierre Gentile (p.gen.progs@gmail.com)
.\"
.\" This Source Code Form is subject to the terms of the Mozilla Public
.\" License, v. 2.0. If a copy of the MPL was not distributed with this
.\" file, You can obtain one at https://mozilla.org/MPL/2.0/.
.\" ###################################################################
.
.SH SYNOPSIS
.sp
\fBsys\fP [\fIoptions\fP\&...] [path]*tag* [\fIarguments\fP\&...]
.sp
\fIoptions\fP can be one of:
.INDENT 0.0
.TP
.B \-d
daemonize
.TP
.BI \-u \ uid
launch with a specific user
.TP
.BI \-g \ uid
launch with a specific group
.TP
.B \-l
list allowed rule for the user
.TP
.B \-v
verbose mode
.TP
.B \-h
synopsis
.UNINDENT
.nf
\fIoptions\fP must appear \fBbefore\fP the tag if any.
\fIarguments\fP are passed to the executable to be run.
.fi
.sp
.SH DESCRIPTION
.sp
In short, \fBsys\fP allows the execution of scripts and binaries as another
user, root by default, in a restricted context.
To do that it needs to have access to a set of \fBrules\fP grouped in at least
one data files.
.sp
The \fBrules\fP must be separated by at least one empty line.
.sp
Each \fBrule\fP may contain:
.INDENT 0.0
.IP \(bu 2
a \fItag\fP (\fBmandatory\fP) starting at the first column,
.IP \(bu 2
various parameters using the syntax: \fBparameter1:[value1[,[value2],...]\fP
preceded by at least one space or tabulation mark.
A \(aq\fB;\fP\(aq can also be used to delimit the values instead of the \(aq\fB,\fP\(aq:
.INDENT 2.0
.IP \(bu 2
a \fIcmd\fP parameter (\fBmandatory\fP) to give the name of the \fIexecutable\fP
and instructions on how to handle its arguments,
.IP \(bu 2
other optional parameters to set or extend the execution environment
of the \fIexecutable\fP or to condition its execution to other criteria.
.UNINDENT
.UNINDENT
.sp
In addition to these \fBrules\fP, data files may also contain \fBvariables\fP
whose purpose is to facilitate the writing of the \fBrule\fP definitions
and make them easier to read and maintain.
.sp
The \fItag\fP is used by \fBsys\fP to locate the correct \fBrule\fP in the
data files.
.sp
If the \fItag\fP is prefixed with a path (starts with a set of strings
delimited by the \fB/\fP character) then only the part after the last
\fB/\fP will be looked for in \fBrules\fP for a match, refer to the \fIpaths\fP
parameter definition in the section named \(dqParameters related to the
execution context.\(dq below.
.sp
If \fBsys\fP cannot find a matching \fBrule\fP for this \fItag\fP, it will
try to use special generic \fBrules\fP identified with \fItags\fP named as
\fB+\fP\fIn\fP where \fIn\fP is a number greater than or equal to 1.
.sp
Note that he existence of these special rules is not mandatory. but in
this case a rule for this \fItag\fP must exist.
.sp
These special \fBrules\fP will be considered in order until one of them
succeeds or the maximum number of attempts is exceeded.
Note that holes are allowed in their numbering sequence.
.sp
The number following \fB+\fP ith their name cannot be greater than \fB8\fP
by default but this value can be increased or decreased using a setting
in the \fBsys\fP configuration file.
See the \fBsys.cfg(5)\fP man page for more details.
.sp
If such special \fBrules\fP exist and no other suitable \fBrule\fP
could be found using the given \fItag\fP, then \fBsys\fP will replace the
pseudo\-executable \fB+\fP in them with the \fItag\fP and try to interpret it
according to the parameters present in that special \fBrule\fP if any.
.sp
Note that \fB+\fP must be the first word in the value of the mandatory \fIcmd\fP
parameter, see below for an example.
.sp
In a way, these special \fBrules\fP can allow \fBsys\fP to be used a bit like
\fBsudo\fP\&.
.sp
Here is a example of a simple \fBrule\fP definition.
The ASCII arrows on the right and the rest of the lines are there for
explanation in this manual, but are not part of the rule definition:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
list <\-\- the tag of the rule passed to sys.
cmd:ls $* <\-\- the (decorated) executable to run.
users:pierre <\-\- a restriction (list can only be used by pierre).
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
With such a definition, when the user enters the command line:
\fBsys list arguments\fP then \fBls arguments\fP is run as root if, and only
if, the real user is \(aqpierre\(aq.
.sp
Note that the tag whose name is \fBlist\fP must start a line without a
leading blank and that the following lines forming the rest of the rule
must be indented.
.sp
Here is an example of how to define a special rule:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
+1
cmd:+ $* <\-\- the \(aq+\(aq is a substitute for the requested command.
environment: <\-\- do not clear the existing environment variables.
groups:root <\-\- members of the root group wont need a password.
password: <\-\- ask for a password in the other cases.
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Warning:
If the \fItag\fP given on the command line is a path (contains a \(aq\fB/\fP\(aq)
then the \fIexecutable\fP value is replaced by the value of the \fItag\fP and
the modified rule will not be cached.
.sp
This kind of \fItags\fP are only taken into account when special \fItags\fP
are defined.
.UNINDENT
.sp
In addition to data files, \fBsys\fP also needs a configuration file whose
content is documented in the \fBsys.cfg(5)\fP man page.
.sp
So, in summary, you\(aqll need:
.INDENT 0.0
.IP \(bu 2
a configuration which must to be named \fBsys.cfg\fP and will be used to
configure \fBsys\fP itself.
It must belong to root and only be readable and writable by root.
It has a simple \fB\&.ini\fP\-like syntax.
Its location in the file system is determined at compile time.
.IP \(bu 2
data files to store the definitions of the \fBrules\fP\&.
They must have a \fB\&.dat\fP suffix and do not have to be located in the
same directory.
.sp
\fB\&.dat\fP files must belong to root and only be readable and writable
by root.
.INDENT 2.0
.IP \(bu 2
\fB\&.dat\fP files are located in directories listed in the \fBsys.cfg\fP
file,
.IP \(bu 2
you can define as many \fB\&.dat\fP files as you like,
.IP \(bu 2
they are parsed in alphabetical order in each directory where they
appear,
.IP \(bu 2
a list of these directories can be given in the in the \fB\&.cfg\fP file
and each of these directories is opened in the order of appearance
in this list,
.IP \(bu 2
if a \fItag\fP appears more than once, the last occurrence on the rule
it tags prevails,
.IP \(bu 2
the \fB\&.dat\fP files can also contain \fBsys\fP \fBvariables\fP whose
scopes are either local (the default) or usable in the \fB\&.dat\fP file
in which they are defined and in all the \fB\&.dat\fP files read \fIafter\fP\&.
.UNINDENT
.UNINDENT
.SS Variables syntax.
.sp
\fBsys\fP \fBvariable\fP are declared in \fB\&.dat\fP files using the
following syntax
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@var:[value]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or for a global variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
global @var:[value]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
they can be expanded using the syntax:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@{var}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A \fBsys\fP \fBvariable\fP cannot be destroyed but can be given an empty
value.
.sp
A \fBvariable\fP definition must start at a beginning of a line in a
\fB\&.dat\fP file, just like a \fItag\fP\&.
.sp
The scope of a \fBvariable\fP is local to the \fB\&.dat\fP file in which it
is defined except when it is a global \fBvariable\fP\&.
The content of a global variable is not reset when parsing the
next \fB\&.dat\fP files.
.sp
\fBVariables\fP (local or global) must be defined before they can be used,
so only objects that appear after their definitions can use them.
.sp
Variables definitions can take more than one line using so called
\fIcontinuation lines\fP\&.
\fIcontinuation lines\fP starts with at least one leading space or tabulation
mark followed by the character \(aq\fB>\fP\(aq and the remaining content value.
.sp
Here is an example of a \fBvariable\fP defined using 3 lines:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@a:first_part\e
>\-second_part\e
>\-last_pert
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is equivalent to:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
@a:first_part\-second_part\-last_pert
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Blanks after the \(aq>\(aq are significant.
.sp
When the last character of a line in a \fBvariable\fP definition is not
followed by a \fB\e\fP, a newline character if automatically inserted when
continuation lines are present.
.SS Rules syntax.
.sp
\fBrules\fP in \fB\&.dat\fP files must be defined using the following syntax:
.INDENT 0.0
.IP \(bu 2
the \fItag\fP must start at the beginning of a line,
.IP \(bu 2
all the following lines describing the parameters on the \fBrule\fP and
must be indented by at least one space or tabulation mark, the number
of these blanks is free and can vary,
.IP \(bu 2
these lines must respect the following syntax:
.INDENT 2.0
.INDENT 3.5
.sp
.nf
.ft C
[!]name:[value1[,value2,...]]
%plugin:plugin_file,plugin_arg1,plugin_arg2,...
$variable:[value]
$pattern:value
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the semicolon (\fB;\fP) can also be used instead of the comma
(\fB,\fP) to separate parameter values.
.sp
Most parameters have their function reversed when prefixed with the
character \(aq\fB!\fP\(aq.
.sp
Some parameters take only zero or one values.
.sp
The variable prefixed by a \(aq\fB$\fP\(aq in the syntax above is an
Unix environment variable, not a \fBsys\fP variable.
.IP \(bu 2
A \fBrule\fP must be followed by at least one empty line (except for
the last one in a given \fB\&.dat\fP file), but cannot contain empty lines.
.UNINDENT
.sp
Here\(aqs an example of a rule:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ksh
cmd:ksh $*
uid:root
gid:sys
$PS1:\(aqsys@${HOSTNAME} # \(aq
environment:
groups:root,@{admin},wheel
paths:/bin,/usr/bin
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As with \fBvariables\fP, each item in an \fBrule\fP can be defined on more than
one line using continuation lines introduced by the continuation character
\(aq\fB>\fP\(aq.
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
groups:root\e
>,@{admin}\e
>,wheel
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The detailed syntax after the \fItag\fP is described below.
.SS Recognized parameters in rules:
.sp
The parameters can be grouped in four categories:
.INDENT 0.0
.IP \(bu 2
those related to the execution context,
.IP \(bu 2
those related to the users,
.IP \(bu 2
those related to restrictions, regular or custom (plugins).
.IP \(bu 2
the \fIcmd\fP parameter describing the command line to be run.
.UNINDENT
.INDENT 0.0
.TP
.B Important:
.INDENT 7.0
.IP \(bu 2
Each parameter can be followed by a comma\-separated list of values.
These values may often be extended regular expressions implicitly
bounded be a starting \fB^\fP and an ending \fB$\fP to prevent stupid
mistakes, we\(aqll call them \(dqconstrained extended regular expressions\(dq
in the following.
.IP \(bu 2
Remember that the semicolon can also be used to delimit parameter
values instead of the comma in the following.
.UNINDENT
.UNINDENT
.SS Parameters related to the execution context.
.INDENT 0.0
.TP
.B \fIenvironment\fP:
The syntax is: \fBenvironment:[\-,][command_line_1,command_line_2,...]\fP
.sp
The negative form (with a leading \fB!\fP) if present will be ignored.
.sp
\fBcommand_line_1\fP, \fBcommand_line_2\fP, ... will be run in sequence
and must provide on their standard outputs a list on lines containing
shell environment variables affectations in the form \fBname=value\fP\&.
The first command on these command lines must include a full path.
.sp
If \fB\-\fP is present then the initial environment will be cleared
before the execution of the command lines.
.sp
if no values are given, then the current environment is inherited
by the command to be executed, possibly completed or surcharged by
some variables, see \fIVariable\fP below.
.sp
Examples:
.INDENT 7.0
.IP \(bu 2
\fBenvironment:\-,/opt/script\fP considers the output of
\fB/opt/script\fP to create a list of environment variable settings
after having cleaned the old environment
.IP \(bu 2
\fBenvironment:\fP transmits the current environment to the
command to be executed possibly completed or altered.
.UNINDENT
.TP
.B \fIEnvironment variable\fP:
The syntax is: \fB$VARIABLE_NAME:value\fP
.sp
\fBVARIABLE_NAME\fP must comply with the command interpreter\(aqs variable
naming rules.
.sp
\fBvalue\fP can be empty in which case the variable will be expanded to
the empty string.
.sp
These variables will be added to the environment of the command which
will be executed and may override variables with the same name if
the existing environment is not empty.
.sp
Example: \fB$PAGER:less\fP
.TP
.B \fIumask\fP:
Syntax:\fBumask:value\fP\&.
.sp
The negative form (with a leading \fB!\fP) if present will be ignored.
.sp
Sets the calling process\(aqs file mode creation mask (umask) in the
target execution environment.
The value of this parameter will be interpreted as an octal number.
.sp
Example: \fBumask:22\fP
.UNINDENT
.SS Parameters related to the user who will be used to run the executable.
.INDENT 0.0
.TP
.B \fIuid\fP:
Syntax:\fBuid:value[,...]\fP\&.
.sp
The negative form (with a leading \fB!\fP) if present will be ignored.
.sp
This parameter sets the UID during the time frame in which the
command will be executed.
.sp
When this parameter is not present, a default value of 0 will be
used and the command will be executed as if you were logged as root.
.sp
When the \fI\-u\fP option is \fBnot\fP used, the first value after the
\fIuid\fP parameter will be used.
.sp
When the \fI\-u\fP option is used, then the requested user must be equal
to one of the values of this parameter.
.sp
\fBvalues\fP can be user names or user ids.
.TP
.B \fIgid\fP:
Syntax:\fBgid:value[,...]\fP\&.
.sp
The negative form (with a leading \fB!\fP) if present will be ignored.
.sp
This parameter is similar to \fIuid\fP but for the group.
.sp
When this parameter is not present, if \fI\-u\fP is \fBnot\fP used, the
group id 0 will be used and the command will be executed as if you
were in the root group, otherwise the primary group of the new user
will be used.
.sp
When the \fI\-g\fP option is \fBnot\fP used, the first value after the \fIgid\fP
parameter is used to set the current group.
.sp
When the \fI\-g\fP option is used then the requested group must be equal
to one of the values of this parameter.
.sp
If the new user is not root, the new group must be one to which the
new user belongs to.
.sp
Also when the new user is not root, the new group must be one of the
new users\(aqs supplementary groups.
.sp
\fBvalue\fP can be a user name or group ids.
.UNINDENT
.SS Parameters related to restrictions.
.INDENT 0.0
.TP
.B \fIdisabled\fP:
Syntax is: \fBdisabled:reason1,reason2,...\fP
.sp
The negative form (with a leading \fB!\fP) if present will be ignored.
.sp
This parameter prohibits the use of the rule. Non\-mandatory values
can be set to provide the user with reasons for disabling this rule.
.sp
Each of these reasons will be printed on a new line in the order
of appearance.
.TP
.B \fIusers\fP:
Syntax is: \fBusers:user[@host][/YYYYMMDD],...]\fP
.sp
This parameter takes as values a comma separated list of items
containing the users \fBallowed\fP to execute the command followed by
optional restrictions.
All the other users will not be permitted to execute it.
.INDENT 7.0
.IP \(bu 2
The \fBuser\fP part of each item can be set by their name or their
UID.
.IP \(bu 2
The optional \fBhost\fP part is a constrained regular expression
describing the hosts from which the user is allowed to execute
the command.
.IP \(bu 2
The optional date part is a string giving the expiration date
using the YYYYMMDDhhmm format.
After this date, the command will not be able to be executed.
.UNINDENT
.sp
If this parameter is prefixed with the character \(aq\fB!\fP\(aq (as in
\fI!users\fP) , then its signification is reversed and the list
designates the users \fBnot allowed\fP to execute the command.
Note that when \(aq\fB!\fP\(aq is used, date limitations are ignored.
.INDENT 7.0
.TP
.B WARNING:
The list of users can be empty, if the parameter is \fI!users\fP,
then the whole rule be immediately denied as all users will be
matched by this parameter.
.sp
if the parameter is \fIusers\fP, the rule will continue to be analyzed
as the users may belong to one of the group or netgroup matched
by the constrained regular expression placed after the parameters
\fIgroups\fP or \fInetgroups\fP of the rule, see below.
.UNINDENT
.sp
Examples:
.INDENT 7.0
.IP \(bu 2
\fBusers:alice/20251010,bob@srv.*/20163112/,carol,100\fP
.IP \(bu 2
\fB!users:carol\fP
.IP \(bu 2
\fBusers:\fP
.UNINDENT
.TP
.B \fIgroups\fP:
same as above but for groups. Primary and secondary groups are
accepted.
.TP
.B \fInetgroups\fP:
same as above but for NIS or LDAP netgroups. Note although than
netgroups in the list of value are not constrained extended regular
expression as in \fIusers\fP and \fIgroups\fP above.
.UNINDENT
.sp
The parameters \fIusers\fP, \fIgroups\fP end \fInetgroups\fP are linked in a way
that it is sufficient for one on them to be accepted for the command
to be run.
This, of course, provided that no other mandatory parameter is rejected.
.sp
When no \fIusers\fP, \fIgroups\fP or \fInetgroups\fP parameter is present in a \fIrule\fP
then any user, group or netgroup will be be accepted.
.sp
The negative forms (with a leading \fB!\fP) of \fIusers\fP, \fIgroups\fP and
\fInetgroups\fP are first checked for a match and if, and only if, no match
has occurred then the positive forms are checked.
This ensures that the filter rules are analyzed regardless of the order
in which they are specified.
.sp
In the same way it if sufficient for him to belong to one of the \(aq\fB!\fP\(aq
prefixed \fIusers\fP, \fIgroups\fP end \fInetgroups\fP parameter to be rejected.
.INDENT 0.0
.TP
.B \fIpaths\fP:
Syntax is: \fBpaths:[path][,...]\fP
.sp
This parameter, which can be negated with \(aq\fB!\fP\(aq list the allowed
(or denied) paths for the target command to belong to.
.sp
The path must be absolute (begin with a \(aq\fB/\fP\(aq).
.sp
If the \fItag\fP given in the command line has a path (contains a \(aq/\(aq)
then a rule for the last part of it (the basename) will be looked for.
If such a rule is found then the path in its command part (if any)
must match the \fItag\fP path and the \fItag\fP\(aqs path must also be present
in the \(dqpaths\(dq parameter\(aqs list and not denied in the \(dq!paths\(dq
parameter list also (if any).
.sp
if the \fItag\fP given in the command line does not have a path then only
the \(dqpaths\(dq and \(dq!paths\(dq parameters (if present) are considered to
enable the \fIexecutable\fP to be run.
.sp
If no path list is given and this parameter is negated with \(aq\fB!\fP\(aq
then the \fIexecutable\fP will \fBnot\fP be ran, otherwise an empty list
of paths does not have any filtering effect.
.TP
.B \fIpassword\fP:
Syntax is: \fBpassword:[user][,...]\fP
.sp
The negative form (with a leading \fB!\fP) if present will be ignored.
.sp
This parameter, if present, allows the user to bypass \(dqusers\(dq, \(dqgroups\(dq
and \(dqnetgroups\(dq filtering failure.
.sp
When this parameter if absent, no password will be asked for and all
filtering failure is fatal.
.sp
If this parameter has a list of values, they will be interpreted as
a list of users.
The password given must be the password of one of them in addition
to the target user and \(aq\fIroot\fP to allow the command to be executed.
The order in which the user\(aqs password is asked for requested will
be the same as the order of the values in this parameter.
.sp
If this parameter if present and none of the parameters \fIusers\fP,
\fIgroups\fP, \fInetgroups\fP or their negations is present or have an empty
set of values, then a password will be asked for.
If at least one of these parameters is present in the rule and has
values, then a password will \fIonly\fP be requested if the current
\fIuser\fP/\fIgroup\fP/\fInetgroup\fP is not in the values given.
.sp
No value for this parameter is equivalent to a list of values
containing \fIroot\fP and the target user.
.sp
On systems when the PAM mechanism is activated, \fBsys\fP can use it for
the authentication, otherwise the encrypted password will be compared
with the one in the shadow database.
.TP
.B \fIowners\fP:
Syntax is: \fBowners:[user:group][,...]\fP
.sp
This parameter, if present, allows to set a list of couples of words
describing the allowed ownership of the executable to be run.
Is the owner of the executable is not found in this list, the rule
will be rejected.
Entries in this list must obey the syntax \fBuser\fP:\fBgroup\fP where
\fBusers\fP and \fBgroup\fP are extended constrained regular expressions.
.INDENT 7.0
.TP
.B Example:
owners:.*:dba,wwwrun:www
.UNINDENT
.sp
The negative form (with a leading \fB!\fP) denies executions instead
of allowing them.
.UNINDENT
.\" COMMENT BLOCK
.\"
.\" *modes*:
.\" If set this parameter impose restrictions on the mode of the
.\" *executable* to be run. The values are constrained regular
.\" expressions and will be tried in sequence.
.\"
.\" The values can be given in the traditional **octal** form with an
.\" optional leading ``0`` or in the **rwxrwxrwx** form as given by the
.\" output of ``ls -l``.
.\"
.\" Example: in ``modes:0754,rwxr--r--`` The second permitted mode is
.\" equivalent to ``744`` in octal.
.\"
.\" Modes descriptions can also have a negated meaning when given after the
.\" parameter *!modes*.
.
.SS Parameter to set the executable name.
.INDENT 0.0
.TP
.B \fIcmd\fP:
Syntax is: \fBcmd:executable\fP
.sp
The negative form (with a leading \fB!\fP) if present will be ignored.
.sp
This is where you have to define the name of the \fIexecutable\fP to
be run.
.INDENT 7.0
.TP
.B WARNING:
\fBsys\fP variables will never been expanded here and will be seen
as ordinary text.
.UNINDENT
.sp
If the \fIexecutable\fP has an absolute path name and the \fIpaths\fP
parameter is also present, then its path must belong to one on the
paths given after the \fIpaths\fP parameter.
.sp
This \fIexecutable\fP can be followed by \fIpatterns\fP to form a pseudo
command line.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
cmd:bash $*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fIpatterns\fP are somewhat similar to the shell\(aqs meta\-characters
and can be seen as substitutes for one or more arguments.
They can be used to control, impose or constrain the arguments of
the \fIexecutable\fP\&.
.sp
Here is the list of all the available \fIpatterns\fP, their meanings
will be detailed below:
.sp
\fB$*\fP, \fB$+\fP, \fB$,\fP, \fB$;\fP, \fB$.\fP, \fB$?\fP, \fB$\fP\fIn\fP and
\fB^\fP\fIword\fP
.sp
All \fIpatterns\fP starting with a \fB$\fP can be prefixed by the character
\fB!\fP to invert their functions.
.sp
\fB$*\fP, \fB$,\fP, \fB$+\fP and \fB?\fP\&. can also be suffixed with a number
to individualize them, so that \fB$*\fP and \fB$*1\fP behave the same but
may have different associated constraints for example.
.sp
Here are some examples of legal \fIpattern\fP names:
\fB$*\fP, \fB$*1\fP, \fB$,\fP, \fB!$\-2\fP, \fB$5\fP, \fB!$1\fP, \fB$+2\fP, \fB$?3\fP,
\fB^\-f\fP
.INDENT 7.0
.TP
.B Important:
During the operation of matching of each \fIpattern\fP to the arguments
provided on the command line, it is important to understand that
a \fIpattern\fP will be used as long as it can be match the arguments
\fBand\fP the next pattern does not also match the current argument,
in which case the next pattern will become the default pattern.
.sp
A command without a \fIpattern\fP does not accept any arguments on
the command line.
.UNINDENT
.sp
\fIpattern\fP features:
.INDENT 7.0
.IP \(bu 2
The \fB$\fP\-patterns can also be filtered/constrained by associating
a filtering \fBparameters\fP to it. see the examples below.
.sp
Here is their detailed meanings:
.INDENT 2.0
.IP \(bu 2
\fB$*\fP expects a (potentially empty) sequence of arguments,
if a filtering parameter is active for \fB$*\fP then all the
given constrained regular expressions must match these arguments
until the next pattern (if any) matches one of them.
.sp
if no filtering parameter is associated to \fB$*\fP, then command line
arguments will be accepted by default until one of them is matched
by the next pattern (if any).
.sp
In other words, \fB$*\fP will eat all matching command line
arguments until it can no longer do so or until the next pattern
matches an argument.
.IP \(bu 2
\fB$+\fP same as for \fB$+\fP but at least one argument must be present.
.IP \(bu 2
\fB$,\fP expects a sequence of arguments, if a filtering parameter is
active for \fB$,\fP then \fBexactly one\fP of its given constrained
regular expressions must match theses arguments.
The other arguments are always accepted until one of them matches
a textual or positional pattern or there is no more argument
to consider.
.IP \(bu 2
\fB$;\fP same a \fB$,\fP except that more then one argument can match
the filter.
.IP \(bu 2
\fB$.\fP expect exactly one argument. If constrained regular
expressions are given then the argument must match one of them.
.IP \(bu 2
\fB$?\fP expect an optional argument. If constrained regular
expressions are given then the argument, if present, must match
one of them.
.IP \(bu 2
\fB$\fP\fIn\fP where \fIn\fP is a number says that the \fIn\fP th argument
must be present. If it has an associated optional filter then this
filter must also match the \fIn\fP th argument.
.sp
\fB$\fP\fIn\fP parameters must appear in increasing order.
.sp
Note that if \fB$\fP\fIn\fP must be preceded by at least one other
pattern if \fIn\fP is greater the 1 to consume the first command line
arguments.
.sp
e.g.
.INDENT 2.0
.INDENT 3.5
\fBcmd:echo $2\fP will always be rejected, \fBcmd:echo $. $2\fP may
succeed
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If the first five type of \fB$\fP\-patterns are followed by a number,
each one is treated independently of the others.
.sp
e.g. when \fB$*1\fP and \fB$*2\fP are present, then each of them can have
a different set of filtering parameters.
.IP \(bu 2
The parameters starting with \fB^\fP mandate that the word that
follows the \fB^\fP must be entered as it is in the command line.
.sp
e.g. \fB^\-a\fP will match the command line argument \fB\-a\fP\&.
.IP \(bu 2
Normal words appearing along the \fIpatterns\fP (those not prefixed
with a \fB$\fP or a \fB^\fP) will be automatically inserted in the command
line and \fBmust not\fP be entered in the command line.
.UNINDENT
.sp
These patterns can be given more than once.
.INDENT 7.0
.TP
.B Examples of pattern usage:
.INDENT 7.0
.TP
.B \fBcmd:executable $*\fP
allows any number of argument (even 0) if no filtering parameter
is set for \fB$*\fP (see below for details about filtering
parameters).
.TP
.B \fBcmd:executable $1\fP
wants exactly one argument whatever it is if no filtering
parameter is set for \fB$1\fP\&.
.TP
.B \fBcmd:executable ^\-a $2\fP
wants exactly one argument whatever it is (if no filtering
parameter is set for \fB$2\fP) after the required argument
\(aq\fB\-a\fP\(aq.
.TP
.B \fBcmd:executable $,1 $,2\fP
when the parameters \fB$,1:\-a\fP and \fB$,2:\-b\fP are present, this
command, wants to see exactly \fBone\fP occurrence of \fB\-a\fP
followed by exactly \fBone\fP occurrence of \fB\-b\fP\&. Each
occurrence can be preceded or followed by any number of other
arguments as in \fB\-x \-a dummy \-y \-b \-z\fP by example.
.TP
.B \fBcmd:executable $. $*\fP
wants any number of arguments with a first argument whose
content can be imposed by a filtering parameter.
.TP
.B \fBcmd:executable $* \-l\fP
allows any number of argument (even 0) if no filtering parameter
is set for \fB$*\fP\&. The \fB\-l\fP argument will be automatically
inserted.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Custom parameters (or plugins) related to restrictions.
.sp
When \fBsys\fP is compiled with plugins enabled (\fB\-\-enable\-plugins\fP),
custom parameters in the form \fI%name\fP are allowed (the leading \fB%\fP
in required).
.sp
The correct syntax for these custom parameters is:
.nf
\fB%plugin_name,plugin_file,arg1,arg2,...\fP
.fi
.sp
.sp
Where \fIplugin_file\fP is the base name of the plugin compiled object
and the \fIargN\fP values are strings which will be passed to the plugin
function at run time.
.sp
Plugins must be compiled and stored in the plugin_directory defined in
\fBsys.cfg\fP (see sys.cfg.5). With \fIgcc\fP for example, the following
instruction can be used:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gcc \-shared \-fPIC \-o plugin_name.so plugin_name.c
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Plugins must have a mandatory public extern function named \fIsys_plugin\fP
respecting the following prototype:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* argc (in) Number of values for this plugin parameter in the rule. */
/* argv (in) Array containing the values for this plugin parameter in */
/* the rule. */
/* output (out) Optional string returned by this plugins, plugins are */
/* responsible to allocate the memory for this string. It */
/* will be freed by sys after its invocation. */
/* output must be NULL if no output is produced. */
/* This string will appear in the sys log file if not NULL. */
/* ===================================================================== */
int sys_plugin_main(int argc, char ** argv, char ** output);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fIplugin_file\fP object file may contain a optional public extern
function returning a version string:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
/* PLugin version function, must return a static string. */
/* ===================================================== */
char * sys_plugin_version(void)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
They \fIsys_plugin_main\fP function must return \fB1\fP on success and \fB0\fP
on failure.
.sp
For security reasons, the directory containing the plugins and the
compiled plugin files must belong to \fBroot\fP:\fBroot\fP and have
permissions respectively equals to \fB0700\fP and \fB0600\fP\&.
.SS Filtering parameter to control the arguments of the target command line.
.sp
Each one of the patters described above may be controlled (filtered) by a
filtering parameter.
.sp
When no filtering parameter is defined for a \fB$\fP\-named \fBcmd\fP
parameter, then they will match any words appearing in the command line.
.sp
Examples of rule extracts with a filtering parameter:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
rmusers
cmd:rm $*
!$*:.*(/\e.\e./.*|/\e.\e.$) <\-\-\- The filtering parameter
$*:/users/.* <\-\-\- restrictions for $*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In this example, \fB$*\fP must match any sequences of words starting
with \fB/users/\fP except those containing \fB/../\fP or those ending with
\fB/..\fP for the command line to be accepted.
.INDENT 0.0
.IP \(bu 2
Examples of \fB$*\fP usages:
.nf
\fBcmd:^\-a $* ^\-b\fP
\fIwithout\fP a \fB$*\fP filtering parameter: