-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathwithlock.1
134 lines (131 loc) · 4.34 KB
/
withlock.1
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
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "WITHLOCK" "1" "June 2015" "" ""
.
.SH "NAME"
\fBwithlock\fR \- locking wrapper script
.
.SH "SYNOPSIS"
\fBwithlock\fR \fIlockfile\fR \fIcommand\fR [\fIargs\fR\.\.\.]
.
.br
\fBwithlock\fR [\fB\-w <seconds>\fR|\fB\-\-wait\fR=\fIseconds\fR] [\fB\-q\fR|\fB\-\-quiet\fR] [\fB\-v\fR|\fB\-\-verbose\fR] \fIlockfile\fR \fIcommand\fR [\fIargs\fR\.\.\.]
.
.br
\fBwithlock\fR [\fB\-h\fR|\fB\-\-help\fR]
.
.br
\fBwithlock\fR [\fB\-\-version\fR]
.
.SH "DESCRIPTION"
withlock(1) is a wrapper script to make sure that some program isn\'t run more than once\. It is ideal to prevent periodic jobs spawned by cron(8) from stacking up\.
.
.P
It uses locks that are valid only while the wrapper is running, and thus will \fInever\fR require additional cleanup, even after a system crash or reboot\. This makes the wrapper safe and easy to use, and better than implementing half\-hearted locking within scripts\.
.
.P
The script can wait a defined time for a lock to become "free"\.
.
.SH "SECURITY"
Lockfiles, generally, MUST NOT be placed in a publicly writable directory, because that would allow for a symlink attack\. For that reason, withlock(1) simply disallows lockfiles in such locations\.
.
.SH "OPTIONS"
.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Print debug messages to stderr\.
.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
If lock can\'t be acquired immediately, silently quit without error\.
.
.TP
\fB\-\-version\fR
Show program\'s version number and exit\.
.
.TP
\fB\-h\fR, \fB\-\-help\fR
Show command synopsis and exit\.
.
.TP
\fB\-w\fR \fIseconds\fR, \fB\-\-wait\fR=\fIseconds\fR
Wait for maximum \fIseconds\fR for the lock to be acquired\.
.
.SH "EXAMPLES"
Instead of your command
.
.IP "" 4
.
.nf
<command> [<args>\.\.\.]
.
.fi
.
.IP "" 0
.
.P
you simply use
.
.IP "" 4
.
.nf
withlock <lockfile> <command> [<args>\.\.\.]
.
.fi
.
.IP "" 0
.
.P
cron(8) jobs, especially long running ones, are frequently run under withlock(1)\. Here\'s an example:
.
.IP "" 4
.
.nf
\-*/10 * * * * root withlock LOCK\-serverstatus /usr/bin/log_server_status2
43 5,17 * * * mirror withlock LOCK\-rsync\-edu\-isos rsync \-rlptoH \-\-no\-motd rsync\.opensuse\-education\.org::download/ISOs/ /srv/mirrors/opensuse\-education/ISOs \-hi
.
.fi
.
.IP "" 0
.
.SH "HISTORY"
This wrapper was implemented because no comparable solution was found even after looking around for a long time (and suffering problems caused by missing or insufficient locking for years)\. The only solution that comes close is with\-lock\-ex\.c, an implementation in C, which was written by Ian Jackson and placed in the public domain by him\. with\-lock\-ex\.c is traditionally available on Debian in a package named chiark\-utils\-bin\. Parts of withlock\'s locking strategy and parts of the usage semantics were inspired from that program\. This implementation was chosen to be done in Python because it\'s universally available, easy to adapt, and doesn\'t require to be compiled\.
.
.P
Then, somebody pointed out to me that there\'s flock(1), a small tool written in C that does the same\. Indeed, I had apparently managed to miss that tool during a decade\'s worth of Linux hacking (you discover something new every day, don\'t you?)\. The functionality is mainly the same indeed\.
.
.P
However, withlock(1) has some advantages:
.
.IP "\(bu" 4
withlock(1) ist a little easier and logical to use than flock(1)\. The semantics are more suited for sysadmins\.
.
.IP "\(bu" 4
withlock(1) always cleans up it\'s lock files\. flock(1) always lets them lying around\. I admit that I like the fact that with withlock(1) I can always see by the presence of the lock files which jobs are running\.
.
.IP "\(bu" 4
flock(1) doesn\'t prevent using unsafe directories
.
.IP "\(bu" 4
withlock(1) is easily extensible
.
.IP "\(bu" 4
it could be used as a Python module (not implemented so far)
.
.IP "\(bu" 4
flock(1) doesn\'t exist on Solaris and OSX
.
.IP "" 0
.
.SH "BUGS"
withlock(1) has been tested on many platforms, including Debian, Ubuntu, openSUSE, CentOS, Fedora, FreeBSD, OSX, OpenCSW Solaris and is in production use since 2009\. There don\'t seem to be race conditions (the author tried very hard to break it) but there are no guarantees\.
.
.SH "AUTHOR"
This program was written by Peter Pöml \fIpeter@poeml\.de\fR in 2009\.
.
.SH "SEE ALSO"
flock(1)
.
.br
with\-lock\-ex(1) from Debian package chiark\-utils\-bin