usr.sbin/ctm/ctm/ctm.1

   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 .\" ----------------------------------------------------------------------------
   7 .\"
   8 .\" This manual page is partially obtained from Poul-Hennings CTM README
   9 .\" file.
  10 .\"
  11 .\" CTM and ctm(1) by <phk@FreeBSD.org>
  12 .\"
  13 .\" $FreeBSD$
  14 .\"
  15 .Dd March 25, 1995
  16 .Dt CTM 1
  17 .Os
  18 .Sh NAME
  19 .Nm ctm
  20 .Nd source code mirror program
  21 .Sh SYNOPSIS
  22 .Nm
  23 .Op Fl cFklquv
  24 .Op Fl b Ar basedir
  25 .Op Fl B Ar backup-file
  26 .Op Fl e Ar include-regex
  27 .Op Fl t Ar tar-command
  28 .Op Fl T Ar tmpdir
  29 .Op Fl V Ar level
  30 .Op Fl x Ar exclude-regex
  31 .Ar
  32 .Sh DESCRIPTION
  33 The
  34 .Nm
  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 .
  39 .Pp
  40 The
  41 .Nm
  42 utility is now meant to be the definitive way to make and apply a delta between
  43 two versions of a directory tree.
  44 .Pp
  45 There are two parts to this, making the delta and applying it.
  46 These are two
  47 entirely different things.
  48 .Ss Usage
  49 To apply a CTM delta, you pass it to the
  50 .Nm
  51 command.
  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.
  57 You can
  58 specify multiple deltas at one time, they will be processed one at a
  59 time.
  60 Deltas that are already applied will be ignored.
  61 .Pp
  62 The
  63 .Nm
  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.
  67 .Pp
  68 Before working on a file
  69 .Ar name
  70 .Nm
  71 first checks for the existence of the file
  72 .Ar name.ctm .
  73 If this file exists,
  74 .Nm
  75 works on it instead.
  76 .Pp
  77 Pass 1 will verify that the input file is OK.
  78 The syntax, the data
  79 and the global MD5 checksum will be checked.
  80 If any of these fail,
  81 .Nm
  82 will simply reject the input file.
  83 .Pp
  84 Pass 2 will validate that the directory tree is in the state expected by
  85 the CTM delta.
  86 This is done by looking for files and directories which
  87 should/should not exist and by checking the MD5 checksums of files.
  88 .Pp
  89 If a
  90 .Ar backup-file
  91 had been specified using the
  92 .Fl B
  93 option, all files that would be modified by this
  94 .Nm
  95 invocation are backed up
  96 to this file using the archiver command specified by the
  97 .Fl t
  98 option.
  99 The default archiver command is
 100 .Nm "tar -rf %s -T -" .
 101 .Pp
 102 Pass 3 will actually apply the delta.
 103 .Pp
 104 The list of files that would be modified by
 105 .Nm
 106 is subject to filtering regular expressions specified
 107 using the
 108 .Fl e
 109 and
 110 .Fl x
 111 options.
 112 The
 113 .Fl e
 114 and
 115 .Fl x
 116 options are applied in order of appearance on the command line.
 117 The last
 118 filter that matched a given file name determines whether the file would be
 119 operated on or left alone by
 120 .Nm .
 121 .Pp
 122 The
 123 .Nm
 124 utility
 125 will extract the file hierarchy below its working directory.
 126 Absolute
 127 filenames or filenames containing references through
 128 .Sq Pa .\&
 129 and
 130 .Sq Pa ..\&
 131 are explicitly prohibited as a security measure.
 132 .Ss Options
 133 .Bl -tag -width indent
 134 .It Fl b Ar basedir
 135 Prepend the path
 136 .Ar basedir
 137 to every filename.
 138 .It Fl B Ar backup-file
 139 Backup all files that would be modified by this CTM run to
 140 .Ar backup-file .
 141 If any filters are specified using the
 142 .Fl e
 143 and
 144 .Fl x
 145 options, then the final set of files backed up are those that would be
 146 modified by CTM after the filters are applied.
 147 .It Fl c
 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.
 153 There may be
 154 any number of these options.
 155 Use of this option disables the
 156 .Pa .ctm_status
 157 sequence number checks.
 158 For example, the expression
 159 .Ic ^usr.sbin/ctm
 160 for example, will select the
 161 .Pa usr.sbin/ctm
 162 source directory and all pathnames under it.
 163 .Pp
 164 Pathnames can be disabled from being considered by CTM using the
 165 .Fl x
 166 option.
 167 .It Fl F
 168 Force.
 169 .It Fl k
 170 Keep files and directories and do not remove them even if the CTM file
 171 specifies they are to be removed.
 172 If the
 173 .Fl B
 174 option is specified, these files and directories will not be backed up.
 175 .It Fl l
 176 List files that would be modified by this invocation of CTM and the
 177 actions that would be performed on them.
 178 Use of the
 179 .Fl l
 180 option disables the
 181 .Pa .ctm_status
 182 checks and integrity checks on the source tree being operated on.
 183 The
 184 .Fl l
 185 option can be combined with the
 186 .Fl e
 187 and
 188 .Fl x
 189 options to determine which files would be modified by the given set of
 190 command line options.
 191 .It Fl q
 192 Tell us less.
 193 .It Fl t Ar tar-command
 194 Use
 195 .Ar tar-command
 196 instead of the default archiver
 197 .Nm tar .
 198 This option takes effect only if a backup file had been specified using the
 199 .Fl B
 200 option.
 201 A %s in the tar command will be replaced by the name of the backup
 202 file.
 203 .It Fl T Ar tmpdir
 204 Put temporary files under
 205 .Ar tmpdir .
 206 .It Fl u
 207 Set modification time of created and modified files to the CTM delta
 208 creation time.
 209 .It Fl v
 210 Tell us more.
 211 .It Fl V Ar level
 212 Tell us more.
 213 .Ar Level
 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
 220 options.
 221 Use of this option disables the
 222 .Pa .ctm_status
 223 sequence number checks.
 224 .Pp
 225 Pathnames can be selected for CTM's consideration using the
 226 .Fl e
 227 option.
 228 .El
 229 .Sh SECURITY
 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
 239 source tree.
 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.
 244 .Pp
 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.
 253 .Pp
 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.
 259 .Sh ENVIRONMENT
 260 .Ev TMPDIR ,
 261 if set to a pathname, will cause ctm to use that pathname
 262 as the location of temporary file.
 263 See
 264 .Xr tempnam 3 ,
 265 for more details on this.
 266 The same effect may be achieved with the
 267 .Fl T
 268 flag.
 269 .Sh FILES
 270 .Pa .ctm_status
 271 contains the sequence number of the last CTM delta applied.
 272 Changing
 273 or removing this file will greatly confuse
 274 .Nm .
 275 .Pp
 276 Using the
 277 .Fl e
 278 and
 279 .Fl x
 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.
 284 .Sh EXAMPLES
 285 .Bd -literal
 286 cd ~cvs
 287 /usr/sbin/ctm ~ctm/cvs-*
 288 .Ed
 289 .Pp
 290 To extract and patch all sources under `lib'
 291 .Bd -literal
 292 cd ~/lib-srcs
 293 /usr/sbin/ctm -e '^lib' ~ctm/src-cur*
 294 .Ed
 295 .Sh DIAGNOSTICS
 296 Numerous messages, hopefully self-explanatory.
 297 The
 298 .Dq noise level
 299 can be adjusted with the
 300 .Fl q ,
 301 .Fl v
 302 and
 303 .Fl V
 304 options.
 305 .Sh SEE ALSO
 306 .Xr ctm_rmail 1 ,
 307 .Xr ctm 5
 308 .Sh HISTORY
 309 Initial trials were run during the work on
 310 .Fx 1.1.5 ,
 311 and many bugs and
 312 methods were hashed out.
 313 .Pp
 314 The
 315 .Nm
 316 command appeared in
 317 .Fx 2.1 .
 318 .Sh AUTHORS
 319 The CTM system has been designed and implemented by
 320 .An Poul-Henning Kamp
 321 .Aq phk@FreeBSD.org .
 322 .Pp
 323 .An Joerg Wunsch
 324 .Aq joerg@FreeBSD.org
 325 wrote this man-page.