1 .\" ----------------------------------------------------------------------------
2 .\" "THE BEER-WARE LICENSE" (Revision 42):
3 .\" <joerg@FreeBSD.org> wrote this file. As long as you retain this notice you
4 .\" can do whatever you want with this stuff. If we meet some day, and you think
5 .\" this stuff is worth it, you can buy me a beer in return. Joerg Wunsch
6 .\" ----------------------------------------------------------------------------
8 .\" This manual page is partially obtained from Poul-Hennings CTM README
11 .\" CTM and ctm(1) by <phk@FreeBSD.org>
20 .Nd source code mirror program
25 .Op Fl B Ar backup-file
26 .Op Fl e Ar include-regex
27 .Op Fl t Ar tar-command
30 .Op Fl x Ar exclude-regex
35 utility was originally
36 .Dq Cvs Through eMail ,
37 but now instead it seems more fitting to call it
38 .Dq Current Through eMail .
42 utility is now meant to be the definitive way to make and apply a delta between
43 two versions of a directory tree.
45 There are two parts to this, making the delta and applying it.
47 entirely different things.
49 To apply a CTM delta, you pass it to the
52 You can pass a CTM delta on stdin, or you can give the
53 filename as an argument.
54 If you do the latter, you make life a lot
55 easier for your self, since the program can accept gzip'ed files and
56 since it will not have to make a temporary copy of your file.
58 specify multiple deltas at one time, they will be processed one at a
60 Deltas that are already applied will be ignored.
64 command runs in a number of passes.
65 It will process the entire
66 input file in each pass, before commencing with the next pass.
68 Before working on a file
71 first checks for the existence of the file
77 Pass 1 will verify that the input file is OK.
79 and the global MD5 checksum will be checked.
82 will simply reject the input file.
84 Pass 2 will validate that the directory tree is in the state expected by
86 This is done by looking for files and directories which
87 should/should not exist and by checking the MD5 checksums of files.
91 had been specified using the
93 option, all files that would be modified by this
95 invocation are backed up
96 to this file using the archiver command specified by the
99 The default archiver command is
100 .Nm "tar -rf %s -T -" .
102 Pass 3 will actually apply the delta.
104 The list of files that would be modified by
106 is subject to filtering regular expressions specified
116 options are applied in order of appearance on the command line.
118 filter that matched a given file name determines whether the file would be
119 operated on or left alone by
125 will extract the file hierarchy below its working directory.
127 filenames or filenames containing references through
131 are explicitly prohibited as a security measure.
133 .Bl -tag -width indent
138 .It Fl B Ar backup-file
139 Backup all files that would be modified by this CTM run to
141 If any filters are specified using the
145 options, then the final set of files backed up are those that would be
146 modified by CTM after the filters are applied.
148 Check it out, do not do anything.
149 .It Fl e Ar regular_expression
150 Match each name in the CTM file against
151 .Ar regular_expression ,
152 and if it matches process the file, otherwise leave it alone.
154 any number of these options.
155 Use of this option disables the
157 sequence number checks.
158 For example, the expression
160 for example, will select the
162 source directory and all pathnames under it.
164 Pathnames can be disabled from being considered by CTM using the
170 Keep files and directories and do not remove them even if the CTM file
171 specifies they are to be removed.
174 option is specified, these files and directories will not be backed up.
176 List files that would be modified by this invocation of CTM and the
177 actions that would be performed on them.
182 checks and integrity checks on the source tree being operated on.
185 option can be combined with the
189 options to determine which files would be modified by the given set of
190 command line options.
193 .It Fl t Ar tar-command
196 instead of the default archiver
198 This option takes effect only if a backup file had been specified using the
201 A %s in the tar command will be replaced by the name of the backup
204 Put temporary files under
207 Set modification time of created and modified files to the CTM delta
214 is the level of verbosity.
215 .It Fl x Ar regular_expression
216 Match each name in the CTM file against
217 .Ar regular_expression
218 and if it matches, leave the file alone.
219 There may be any number of these
221 Use of this option disables the
223 sequence number checks.
225 Pathnames can be selected for CTM's consideration using the
230 On its own, CTM is an insecure protocol
231 - there is no authentication performed that the
232 changes applied to the source code were sent by a
233 trusted party, and so care should be taken if the
234 CTM deltas are obtained via an unauthenticated
235 medium such as regular email.
236 It is a relatively simple matter for an attacker
237 to forge a CTM delta to replace or precede the
238 legitimate one and insert malicious code into your
240 If the legitimate delta is somehow prevented from
241 arriving, this will go unnoticed until a later
242 delta attempts to touch the same file, at which
243 point the MD5 checksum will fail.
245 To remedy this insecurity, CTM pieces generated by
246 FreeBSD.org are cryptographically signed in a
247 format compatible with the GNU Privacy Guard
248 utility, available in /usr/ports/security/gpg, and
249 the Pretty Good Privacy v5 utility,
250 /usr/ports/security/pgp5.
251 The relevant public key can be obtained by
252 fingering ctm@FreeBSD.org.
254 CTM deltas which are thus signed cannot be
255 undetectably altered by an attacker.
256 Therefore it is recommended that you make use of
257 GPG or PGP5 to verify the signatures if you
258 receive your CTM deltas via email.
261 if set to a pathname, will cause ctm to use that pathname
262 as the location of temporary file.
265 for more details on this.
266 The same effect may be achieved with the
271 contains the sequence number of the last CTM delta applied.
273 or removing this file will greatly confuse
280 options can update a partial subset of the source tree and causes sources
281 to be in an inconsistent state.
282 It is assumed that you know what you are
283 doing when you use these options.
287 /usr/sbin/ctm ~ctm/cvs-*
290 To extract and patch all sources under `lib'
293 /usr/sbin/ctm -e '^lib' ~ctm/src-cur*
296 Numerous messages, hopefully self-explanatory.
299 can be adjusted with the
309 Initial trials were run during the work on
312 methods were hashed out.
319 The CTM system has been designed and implemented by
320 .An Poul-Henning Kamp
321 .Aq phk@FreeBSD.org .
324 .Aq joerg@FreeBSD.org