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
|
.\"----------------------------------------------------------------------------
.\""THE BEER-WARE LICENSE" (Revision 42):
.\"<joerg@freebsd.org> wrote this file. As long as you retain this notice you
.\"can do whatever you want with this stuff. If we meet some day, and you think
.\"this stuff is worth it, you can buy me a beer in return. Joerg Wunsch
.\"----------------------------------------------------------------------------
.\"
.\" This manual page is partially obtained from Poul-Hennings CTM README
.\" file.
.\"
.\" CTM and ctm(1) by <phk@login.dknet.dk>
.\"
.\" $FreeBSD$
.\"
.Dd March 25, 1995
.Os
.Dt CTM 1
.Sh NAME
.Nm ctm
.Nd source code mirror program
.Sh SYNOPSIS
.Nm
.Op Fl cFklquv
.Op Fl b Ar basedir
.Op Fl B Ar backup-file
.Op Fl e Ar include-regex
.Op Fl t Ar tar-command
.Op Fl T Ar tmpdir
.Op Fl V Ar level
.Op Fl x Ar exclude-regex
.Ar
.Sh DESCRIPTION
.Nm Ctm
was originally
.Dq Cvs Through eMail ,
but now instead it seems more fitting to call it
.Dq Current Through eMail .
.Pp
.Nm Ctm
is now meant to be the definitive way to make and apply a delta between
two versions of a directory tree.
.Pp
There are two parts to this, making the delta and applying it. These are two
entirely different things.
.Ss Usage
To apply a CTM delta, you pass it to the
.Nm
command. You can pass a CTM delta on stdin, or you can give the
filename as an argument. If you do the latter, you make life a lot
easier for your self, since the program can accept gzip'ed files and
since it will not have to make a temporary copy of your file. You can
specify multiple deltas at one time, they will be processed one at a
time. Deltas that are already applied will be ignored.
.Pp
The
.Nm
command runs in a number of passes. It will process the entire
input file in each pass, before commencing with the next pass.
.Pp
Before working on a file
.Ar name
.Nm
first checks for the existence of the file
.Ar name.ctm .
If this file exists,
.Nm
works on it instead.
.Pp
Pass 1 will verify that the input file is OK. The syntax, the data
and the global MD5 checksum will be checked. If any of these fail,
.Nm
will simply reject the input file.
.Pp
Pass 2 will validate that the directory tree is in the state expected by
the CTM delta. This is done by looking for files and directories which
should/should not exist and by checking the MD5 checksums of files.
.Pp
If a
.Ar backup-file
had been specified using the
.Fl B
option, all files that would be modified by this
.Nm
invocation are backed up
to this file using the archiver command specified by the
.Fl t
option. The default archiver command is
.Nm "tar -rf %s -T -" .
.Pp
Pass 3 will actually apply the delta.
.Pp
The list of files that would be modified by
.Nm
is subject to filtering regular expressions specified
using the
.Fl e
and
.Fl x
options.
The
.Fl e
and
.Fl x
options are applied in order of appearance on the command line. The last
filter that matched a given file name determines whether the file would be
operated on or left alone by
.Nm .
.Pp
.Nm Ctm
will extract the file hierarchy below its working directory. Absolute
filenames or filenames containing references through
.Sq Pa .\&
and
.Sq Pa ..\&
are explicitly prohibited as a security measure.
.Ss Options
.Bl -tag -width indent
.It Fl b Ar basedir
Prepend the path
.Ar basedir
to every filename.
.It Fl B Ar backup-file
Backup all files that would be modified by this CTM run to
.Ar backup-file .
If any filters are specified using the
.Fl e
and
.Fl x
options, then the final set of files backed up are those that would be
modified by CTM after the filters are applied.
.It Fl c
Check it out, don't do anything.
.It Fl e Ar regular_expression
Match each name in the CTM file against
.Ar regular_expression ,
and if it matches process the file, otherwise leave it alone. There may be
any number of these options. Use of this option disables the
.Pa .ctm_status
sequence number checks. For example, the expression
.Ic ^usr.sbin/ctm
for example, will select the
.Nm usr.sbin/ctm
source directory and all pathnames under it.
.Pp
Pathnames can be disabled from being considered by CTM using the
.Fl x
option.
.It Fl F
Force.
.It Fl k
Keep files and directories and don't remove them even if the CTM file
specifies they are to be removed. If the
.Fl B
option is specified, these files and directories will not be backed up.
.It Fl l
List files that would be modified by this invocation of CTM and the
actions that would be performed on them. Use of the
.Fl l
option disables the
.Pa .ctm_status
checks and integrity checks on the source tree being operated on. The
.Fl l
option can be combined with the
.Fl e
and
.Fl x
options to determine which files would be modified by the given set of
command line options.
.It Fl q
Tell us less.
.It Fl t Ar tar-command
Use
.Ar tar-command
instead of the default archiver
.Nm tar .
This option takes effect only if a backup file had been specified using the
.Fl B
option. A %s in the tar command will be replaced by the name of the backup
file.
.It Fl T Ar tmpdir
Put temporary files under
.Ar tmpdir .
.It Fl u
Set modification time of created and modified files to the CTM delta
creation time.
.It Fl v
Tell us more.
.It Fl V Ar level
Tell us more.
.Ar Level
is the level of verbosity.
.It Fl x Ar regular_expression
Match each name in the CTM file against
.Ar regular_expression
and if it matches, leave the file alone. There may be any number of these
options. Use of this option disables the
.Pa .ctm_status
sequence number checks.
.Pp
Pathnames can be selected for CTM's consideration using the
.Fl e
option.
.El
.Pp
.Sh SECURITY
.Pp
On its own, CTM is an insecure protocol
- there is no authentication performed that the
changes applied to the source code were sent by a
trusted party, and so care should be taken if the
CTM deltas are obtained via an unauthenticated
medium such as regular email.
It is a relatively simple matter for an attacker
to forge a CTM delta to replace or precede the
legitimate one and insert malicious code into your
source tree.
If the legitimate delta is somehow prevented from
arriving, this will go unnoticed until a later
delta attempts to touch the same file, at which
point the MD5 checksum will fail.
.Pp
To remedy this insecurity, CTM pieces generated by
freebsd.org are cryptographically signed in a
format compatible with the GNU Privacy Guard
utility, available in /usr/ports/security/gpg, and
the Pretty Good Privacy v5 utility,
/usr/ports/security/pgp5.
The relevant public key can be obtained by
fingering ctm@freebsd.org.
.Pp
CTM deltas which are thus signed cannot be
undetectably altered by an attacker.
Therefore it is recommended that you make use of
GPG or PGP5 to verify the signatures if you
receive your CTM deltas via email.
.Sh ENVIRONMENT
.Ev TMPDIR,
if set to a pathname, will cause ctm to use that pathname
as the location of temporary file.
See
.Xr tempnam 3 ,
for more details on this.
The same effect may be achieved with the
.Fl T
flag.
.Sh FILES
.Pa .ctm_status
contains the sequence number of the last CTM delta applied. Changing
or removing this file will greatly confuse
.Nm .
.Pp
Using the
.Fl e
and
.Fl x
options can update a partial subset of the source tree and causes sources
to be in an inconsistent state. It is assumed that you know what you are
doing when you use these options.
.Sh EXAMPLES
.Bd -literal
cd ~cvs
/usr/sbin/ctm ~ctm/cvs-*
.Ed
.Pp
To extract and patch all sources under `lib'
.Bd -literal
cd ~/lib-srcs
/usr/sbin/ctm -e '^lib' ~ctm/src-cur*
.Ed
.Sh DIAGNOSTICS
Numerous messages, hopefully self-explanatory. The
.Dq noise level
can be adjusted with the
.Fl q ,
.Fl v
and
.Fl V
options.
.Sh SEE ALSO
.Xr ctm_rmail 1 ,
.Xr ctm 5
.Sh HISTORY
Initial trials were run during the work on
.Fx 1.1.5 ,
and many bugs and
methods were hashed out.
.Pp
The
.Nm
command appeared in
.Fx 2.1 .
.Sh AUTHORS
The CTM system has been designed and implemented by
.An Poul-Henning Kamp
.Aq phk@FreeBSD.org .
.Pp
.An Joerg Wunsch
.Aq joerg@FreeBSD.org
wrote this man-page.
|