Skip to content

Commit bf0ea1b

Browse files
albersalbers
committed
Represent Linux capabilites as an enum
This avoids errors when entering capabilities due to different capabilty names, e.g. "MKNOD" in docker vs. "CAP_MKNOD" in Linux manpages. It also gives a natural home for documenting the meaning of the individual values.
1 parent d2d9744 commit bf0ea1b

File tree

6 files changed

+385
-24
lines changed

6 files changed

+385
-24
lines changed

‎src/main/java/com/github/dockerjava/api/command/StartContainerCmd.java‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import com.github.dockerjava.api.NotFoundException;
44
import com.github.dockerjava.api.NotModifiedException;
55
import com.github.dockerjava.api.model.Bind;
6+
import com.github.dockerjava.api.model.Capability;
67
import com.github.dockerjava.api.model.Device;
78
import com.github.dockerjava.api.model.Link;
89
import com.github.dockerjava.api.model.LxcConf;
@@ -41,9 +42,9 @@ public interface StartContainerCmd extends DockerCmd<Void> {
4142

4243
public RestartPolicy getRestartPolicy();
4344

44-
public String[] getCapAdd();
45+
public Capability[] getCapAdd();
4546

46-
public String[] getCapDrop();
47+
public Capability[] getCapDrop();
4748

4849
public StartContainerCmd withBinds(Bind... binds);
4950

@@ -115,18 +116,18 @@ public interface StartContainerCmd extends DockerCmd<Void> {
115116
/**
116117
* Add linux <a
117118
* href="http://man7.org/linux/man-pages/man7/capabilities.7.html">kernel
118-
* capability</a> to the container. For example: adding capability "MKNOD"
119+
* capability</a> to the container. For example: adding {@link Capability#MKNOD}
119120
* allows the container to create special files using the 'mknod' command.
120121
*/
121-
public StartContainerCmd withCapAdd(String... capAdd);
122+
public StartContainerCmd withCapAdd(Capability... capAdd);
122123

123124
/**
124125
* Drop linux <a
125126
* href="http://man7.org/linux/man-pages/man7/capabilities.7.html">kernel
126-
* capability</a> from the container. For example: dropping capability
127-
* "CHOWN" prevents the container from changing the owner of any files.
127+
* capability</a> from the container. For example: dropping {@link Capability#CHOWN}
128+
* prevents the container from changing the owner of any files.
128129
*/
129-
public StartContainerCmd withCapDrop(String... capDrop);
130+
public StartContainerCmd withCapDrop(Capability... capDrop);
130131

131132
/**
132133
* @throws NotFoundException

‎src/main/java/com/github/dockerjava/api/model/Capability.java‎

Lines changed: 329 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,329 @@
1+
package com.github.dockerjava.api.model;
2+
3+
/**
4+
* The Linux capabilities supported by Docker.
5+
* The list of capabilities is defined in Docker's types.go,
6+
* {@link #ALL} was added manually.
7+
*
8+
* @see <a href="http://man7.org/linux/man-pages/man7/capabilities.7.html">http://man7.org/linux/man-pages/man7/capabilities.7.html</a>
9+
*/
10+
public enum Capability {
11+
/**
12+
* This meta capability includes all Linux capabilities.
13+
*/
14+
ALL,
15+
/**
16+
* <ul>
17+
* <li>Enable and disable kernel auditing.
18+
* <li>Change auditing filter rules.
19+
* <li>Retrieve auditing status and filtering rules.
20+
* </ul>
21+
*/
22+
AUDIT_CONTROL,
23+
/**
24+
* Write records to kernel auditing log.
25+
*/
26+
AUDIT_WRITE,
27+
/**
28+
* Employ features that can block system suspend.
29+
*/
30+
BLOCK_SUSPEND,
31+
/**
32+
* Make arbitrary changes to file UIDs and GIDs (see chown(2)).
33+
*/
34+
CHOWN,
35+
/**
36+
* Bypass file read, write, and execute permission checks.
37+
* (DAC is an abbreviation of "discretionary access control".)
38+
*/
39+
DAC_OVERRIDE,
40+
/**
41+
* Bypass file read permission checks and directory read and
42+
* execute permission checks.
43+
*/
44+
DAC_READ_SEARCH,
45+
/**
46+
* <ul>
47+
* <li>Bypass permission checks on operations that normally require
48+
* the file system UID of the process to match the UID of the file
49+
* (e.g., chmod(2), utime(2)), excluding those operations covered
50+
* by the {@link #DAC_OVERRIDE} and{@link #DAC_READ_SEARCH}.
51+
* <li>Set extended file attributes (see chattr(1)) on arbitrary files.
52+
* <li>Set Access Control Lists (ACLs) on arbitrary files.
53+
* <li>Ignore directory sticky bit on file deletion.
54+
* <li>Specify O_NOATIME for arbitrary files in open(2)and fcntl(2).
55+
* </ul>
56+
*/
57+
FOWNER,
58+
/**
59+
* <ul>
60+
* <li>Don't clear set-user-ID and set-group-ID permission bits when
61+
* a file is modified.
62+
* <li>Set the set-group-ID bit for a file whose GID does not match
63+
* the file system or any of the supplementary GIDs of the calling
64+
* process.
65+
* </ul>
66+
*/
67+
FSETID,
68+
/**
69+
* Permit memory locking (mlock(2), mlockall(2), mmap(2), shmctl(2)).
70+
*/
71+
IPC_LOCK,
72+
/**
73+
* Bypass permission checks for operations on System V IPC objects.
74+
*/
75+
IPC_OWNER,
76+
/**
77+
* Bypass permission checks for sending signals (see kill(2)).
78+
* This includes use of the ioctl(2) KDSIGACCEPT operation.
79+
*/
80+
KILL,
81+
/**
82+
* Establish leases on arbitrary files (see fcntl(2)).
83+
*/
84+
LEASE,
85+
/**
86+
* Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags (see chattr(1)).
87+
*/
88+
LINUX_IMMUTABLE,
89+
/**
90+
* Override Mandatory Access Control (MAC).
91+
* Implemented for the Smack Linux Security Module (LSM).
92+
*/
93+
MAC_ADMIN,
94+
/**
95+
* Allow MAC configuration or state changes. Implemented for the Smack LSM.
96+
*/
97+
MAC_OVERRIDE,
98+
/**
99+
* Create special files using mknod(2).
100+
*/
101+
MKNOD,
102+
/**
103+
* Perform various network-related operations:
104+
* <ul>
105+
* <li>Interface configuration.
106+
* <li>Administration of IP firewall, masquerading, and accounting.
107+
* <li>Modify routing tables.
108+
* <li>Bind to any address for transparent proxying.
109+
* <li>Set type-of-service (TOS).
110+
* <li>Clear driver statistics.
111+
* <li>Set promiscuous mode.
112+
* <li>Enabling multicasting.
113+
* <li>Use setsockopt(2) to set the following socket options: SO_DEBUG,
114+
* SO_MARK, SO_PRIORITY (for a priority outside the range 0 to 6),
115+
* SO_RCVBUFFORCE, and SO_SNDBUFFORCE.
116+
* </ul>
117+
*/
118+
NET_ADMIN,
119+
/**
120+
* Bind a socket to Internet domain privileged ports (port numbers less
121+
* than 1024).
122+
*/
123+
NET_BIND_SERVICE,
124+
/**
125+
* (Unused) Make socket broadcasts, and listen to multicasts.
126+
*/
127+
NET_BROADCAST,
128+
/**
129+
* <ul>
130+
* <li>Use RAW and PACKET sockets.
131+
* <li>Bind to any address for transparent proxying.
132+
* </ul>
133+
*/
134+
NET_RAW,
135+
/**
136+
* Set file capabilities.
137+
*/
138+
SETFCAP,
139+
/**
140+
* <ul>
141+
* <li>Make arbitrary manipulations of process GIDs and supplementary
142+
* GID list.
143+
* <li>Forge GID when passing socket credentials via UNIX domain
144+
* sockets.
145+
* </ul>
146+
*/
147+
SETGID,
148+
/**
149+
* If file capabilities are not supported:
150+
* <ul>
151+
* <li>grant or remove any capability in the caller's permitted
152+
* capability set to or from any other process. (This property of
153+
* CAP_SETPCAP is not available when the kernel is configured to
154+
* support file capabilities, since CAP_SETPCAP has entirely different
155+
* semantics for such kernels.)
156+
* </ul>
157+
* <p>
158+
* If file capabilities are supported:
159+
* <ul>
160+
* <li>Add any capability from the calling thread's bounding set to its
161+
* inheritable set.
162+
* <li>Drop capabilities from the bounding set (via prctl(2)
163+
* PR_CAPBSET_DROP).
164+
* <li>Make changes to the securebits flags.
165+
* </ul>
166+
*/
167+
SETPCAP,
168+
/**
169+
* <ul>
170+
* <li>Make arbitrary manipulations of process UIDs (setuid(2),
171+
* setreuid(2), setresuid(2), setfsuid(2)).
172+
* <li>Make forged UID when passing socket credentials via UNIX domain
173+
* sockets.
174+
* </ul>
175+
*/
176+
SETUID,
177+
/**
178+
* <ul>
179+
* <li>Perform a range of system administration operations including:
180+
* quotactl(2), mount(2), umount(2), swapon(2), swapoff(2), sethostname(2),
181+
* and setdomainname(2).
182+
* <li>Perform privileged syslog(2) operations (since Linux 2.6.37,
183+
* CAP_SYSLOG should be used to permit such operations).
184+
* <li>Perform VM86_REQUEST_IRQ vm86(2) command.
185+
* <li>Perform IPC_SET and IPC_RMID operations on arbitrary System V IPC objects.
186+
* <li>Perform operations on trusted and security Extended Attributes
187+
* (see attr(5)).
188+
* <li>Use lookup_dcookie(2)
189+
* <li>Use ioprio_set(2) to assign IOPRIO_CLASS_RT and (before Linux 2.6.25)
190+
* IOPRIO_CLASS_IDLE I/O scheduling classes.
191+
* <li>Forge UID when passing socket credentials.
192+
* <li>Exceed /proc/sys/fs/file-max, the system-wide limit on the number of
193+
* open files, in system calls that open files (e.g., accept(2), execve(2),
194+
* open(2), pipe(2)).
195+
* <li>Employ CLONE_* flags that create new namespaces with clone(2) and
196+
* unshare(2).
197+
* <li>Call perf_event_open(2).
198+
* <li>Access privileged perf event information.
199+
* <li>Call setns(2).
200+
* <li>Call fanotify_init(2).
201+
* <li>Perform KEYCTL_CHOWN and KEYCTL_SETPERM keyctl(2) operations.
202+
* <li>Perform madvise(2) MADV_HWPOISON operation.
203+
* <li>Employ the TIOCSTI ioctl(2) to insert characters into the input queue
204+
* of a terminal other than the caller's controlling terminal.
205+
* <li>Employ the obsolete nfsservctl(2) system call.
206+
* <li>Employ the obsolete bdflush(2) system call.
207+
* <li>Perform various privileged block-device ioctl(2) operations.
208+
* <li>Perform various privileged file-system ioctl(2) operations.
209+
* <li>Perform administrative operations on many device drivers.
210+
* </ul>
211+
*/
212+
SYS_ADMIN,
213+
/**
214+
* Use reboot(2) and kexec_load(2).
215+
*/
216+
SYS_BOOT,
217+
/**
218+
* Use chroot(2).
219+
*/
220+
SYS_CHROOT,
221+
/**
222+
* <ul>
223+
* <li>Perform privileged syslog(2) operations. See syslog(2) for information
224+
* on which operations require privilege.
225+
* <li>View kernel addresses exposed via /proc and other interfaces when
226+
* /proc/sys/kernel/kptr_restrict has the value 1. (See the discussion of the
227+
* kptr_restrict in proc(5).)
228+
* </ul>
229+
*/
230+
SYSLOG,
231+
/**
232+
* <ul>
233+
* <li>Load and unload kernel modules (see init_module(2) and delete_module(2))
234+
* <li>In kernels before 2.6.25: drop capabilities from the system-wide
235+
* capability bounding set.
236+
* </ul>
237+
*/
238+
SYS_MODULE,
239+
/**
240+
* <ul>
241+
* <li>Raise process nice value (nice(2), setpriority(2)) and change the nice
242+
* value for arbitrary processes.
243+
* <li>Set real-time scheduling policies for calling process, and set scheduling
244+
* policies and priorities for arbitrary processes (sched_setscheduler(2),
245+
* sched_setparam(2)).
246+
* <li>Set CPU affinity for arbitrary processes (sched_setaffinity(2)).
247+
* <li>Set I/O scheduling class and priority for arbitrary processes
248+
* (ioprio_set(2)).
249+
* <li>Apply migrate_pages(2) to arbitrary processes and allow processes to be
250+
* migrated to arbitrary nodes.
251+
* <li>Apply move_pages(2) to arbitrary processes.
252+
* <li>Use the MPOL_MF_MOVE_ALL flag with mbind(2) and move_pages(2).
253+
* </ul>
254+
*/
255+
SYS_NICE,
256+
/**
257+
* Use acct(2).
258+
*/
259+
SYS_PACCT,
260+
/**
261+
* <ul>
262+
* <li>Trace arbitrary processes using ptrace(2).
263+
* <li>Apply get_robust_list(2) to arbitrary processes.
264+
* <li>Inspect processes using kcmp(2).
265+
* </ul>
266+
*/
267+
SYS_PTRACE,
268+
/**
269+
* <ul>
270+
* <li>Perform I/O port operations (iopl(2) and ioperm(2)).
271+
* <li>Access /proc/kcore.
272+
* <li>Employ the FIBMAP ioctl(2) operation.
273+
* <li>Open devices for accessing x86 model-specific registers (MSRs, see
274+
* msr(4)).
275+
* <li>Update /proc/sys/vm/mmap_min_addr.
276+
* <li>Create memory mappings at addresses below the value specified by
277+
* /proc/sys/vm/mmap_min_addr.
278+
* <li>Map files in /proc/pci/bus.
279+
* <li>Open /dev/mem and /dev/kmem.
280+
* <li>Perform various SCSI device commands.
281+
* <li>Perform certain operations on hpsa(4) and cciss(4) devices.
282+
* <li>Perform a range of device-specific operations on other devices.
283+
* </ul>
284+
*/
285+
SYS_RAWIO,
286+
/**
287+
* <ul>
288+
* <li>Use reserved space on ext2 file systems.
289+
* <li>Make ioctl(2) calls controlling ext3 journaling.
290+
* <li>Override disk quota limits.
291+
* <li>Increase resource limits (see setrlimit(2)).
292+
* <li>Override RLIMIT_NPROC resource limit.
293+
* <li>Override maximum number of consoles on console allocation.
294+
* <li>Override maximum number of keymaps.
295+
* <li>Allow more than 64hz interrupts from the real-time clock.
296+
* <li>Raise msg_qbytes limit for a System V message queue above the limit
297+
* in /proc/sys/kernel/msgmnb (see msgop(2) and msgctl(2)).
298+
* <li>Override the /proc/sys/fs/pipe-size-max limit when setting the capacity
299+
* of a pipe using the F_SETPIPE_SZ fcntl(2) command.
300+
* <li>Use F_SETPIPE_SZ to increase the capacity of a pipe above the limit
301+
* specified by /proc/sys/fs/pipe-max-size.
302+
* <li>Override /proc/sys/fs/mqueue/queues_max limit when creating POSIX
303+
* message queues (see mq_overview(7)).
304+
* <li>Employ prctl(2) PR_SET_MM operation.
305+
* <li>Set /proc/PID/oom_score_adj to a value lower than the value last set
306+
* by a process with CAP_SYS_RESOURCE.
307+
* </ul>
308+
*/
309+
SYS_RESOURCE,
310+
/**
311+
* <ul>
312+
* <li>Set system clock (settimeofday(2), stime(2), adjtimex(2)).
313+
* <li>Set real-time (hardware) clock.
314+
* </ul>
315+
*/
316+
SYS_TIME,
317+
/**
318+
* <ul>
319+
* <li>Use vhangup(2).
320+
* <li>Employ various privileged ioctl(2) operations on virtual terminals.
321+
* </ul>
322+
*/
323+
SYS_TTY_CONFIG,
324+
/**
325+
* Trigger something that will wake up the system (set CLOCK_REALTIME_ALARM and
326+
* CLOCK_BOOTTIME_ALARM timers).
327+
*/
328+
WAKE_ALARM
329+
}

0 commit comments

Comments
 (0)