seccomp: extend manpage, and add examples

Signed-off-by: Serge Hallyn <serge.hallyn@ubuntu.com>
Acked-by: Stéphane Graber <stgraber@ubuntu.com>

doc/examples/Makefile.am

@@ -8,7 +8,10 @@ pkgexamples_DATA = \
 	lxc-empty-netns.conf \
 	lxc-phys.conf \
 	lxc-veth.conf \
-	lxc-complex.conf
+	lxc-complex.conf \
+	seccomp-v1.conf \
+	seccomp-v2-blacklist.conf \
+	seccomp-v2.conf
 endif
 
 noinst_DATA = \
@@ -18,4 +21,7 @@ noinst_DATA = \
 	lxc-no-netns.conf.in \
 	lxc-phys.conf.in \
 	lxc-veth.conf.in \
-	lxc-complex.conf.in
+	lxc-complex.conf.in \
+	seccomp-v1.conf \
+	seccomp-v2-blacklist.conf \
+	seccomp-v2.conf

doc/examples/seccomp-v1.conf

@@ -0,0 +1,359 @@
+1
+whitelist
+0
+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
+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

doc/examples/seccomp-v2-blacklist.conf

@@ -0,0 +1,8 @@
+2
+blacklist
+# v2 allows comments after the second line, with '#' in first column,
+# blacklist will allow syscalls by default
+# if 'errno 0' was not appended to 'mknod' below, then the task would
+# simply be killed when it tried to mknod.  'errno 0' means do not allow
+# the container to mknod, but immediately return 0.
+mknod errno 0

doc/examples/seccomp-v2.conf

@@ -0,0 +1,24 @@
+2
+whitelist trap
+# 'whitelist' would normally mean kill a task doing any syscall which is not
+# whitelisted below.  By appending 'trap' to the line, we will cause a SIGSYS
+# to be sent to the task instead.  'errno 0' would  mean don't allow the system
+# call but immediately return 0.  'errno 22' would mean return EINVAL immediately.
+[x86_64]
+open
+close
+read
+write
+mount
+umount2
+# Since we are listing system calls by name, we can also ask to have them resolved
+# for another arch, i.e. for 32/64-bit versions.
+[x86]
+open
+close
+read
+write
+mount
+umount2
+# Do note that this policy does not whitelist enough system calls to allow a
+# system container to boot.

doc/lxc.container.conf.sgml.in

@@ -1015,11 +1015,33 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
       <para>
         A container can be started with a reduced set of available
 	system calls by loading a seccomp profile at startup.  The
-	seccomp configuration file should begin with a version number
+	seccomp configuration file must begin with a version number
-	(which currently must be 1) on the first line, a policy type
+	on the first line, a policy type on the second line, followed
-	(which must be 'whitelist') on the second line, followed by a
+	by the configuration.
-	list of allowed system call numbers, one per line.
       </para>
+      <para>
+        Versions 1 and 2 are currently supported.  In version 1, the
+	policy is a simple whitelist.  The second line therefore must
+	read "whitelist", with the rest of the file containing one (numeric)
+	sycall number per line.  Each syscall number is whitelisted,
+	while every unlisted number is blacklisted for use in teh container
+      </para>
+
+      <para>
+       In version 2, the policy may be blacklist or whitelist,
+       supports per-rule and per-policy default actions, and supports
+       per-architecture system call resolution from textual names.
+      </para>
+      <para>
+       An example blacklist policy, in which all system calls are
+       allowed except for mknod, which will simply do nothing and
+       return 0 (success), looks like:
+      </para>
+<screen>
+2
+blacklist
+mknod errno 0
+</screen>
       <variablelist>
 	<varlistentry>
 	  <term>