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: src/usr.sbin/ctm/ctm/ctm.1,v 1.17.2.9 2003/03/12 22:08:14 trhodes Exp $
  14 .\" $DragonFly: src/usr.sbin/ctm/ctm/Attic/ctm.1,v 1.2 2003/06/17 04:29:53 dillon Exp $
  15 .\"
  16 .Dd March 25, 1995
  17 .Os
  18 .Dt CTM 1
  19 .Sh NAME
  20 .Nm ctm
  21 .Nd source code mirror program
  22 .Sh SYNOPSIS
  23 .Nm
  24 .Op Fl cFklquv
  25 .Op Fl b Ar basedir
  26 .Op Fl B Ar backup-file
  27 .Op Fl e Ar include-regex
  28 .Op Fl t Ar tar-command
  29 .Op Fl T Ar tmpdir
  30 .Op Fl V Ar level
  31 .Op Fl x Ar exclude-regex
  32 .Ar
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 utility was originally
  37 .Dq Cvs Through eMail ,
  38 but now instead it seems more fitting to call it
  39 .Dq Current Through eMail .
  40 .Pp
  41 The
  42 .Nm
  43 utility is now meant to be the definitive way to make and apply a delta between
  44 two versions of a directory tree.
  45 .Pp
  46 There are two parts to this, making the delta and applying it.  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.  You can pass a CTM delta on stdin, or you can give the
  52 filename as an argument.  If you do the latter, you make life a lot
  53 easier for your self, since the program can accept gzip'ed files and
  54 since it will not have to make a temporary copy of your file.  You can
  55 specify multiple deltas at one time, they will be processed one at a
  56 time.  Deltas that are already applied will be ignored.
  57 .Pp
  58 The
  59 .Nm
  60 command runs in a number of passes.  It will process the entire
  61 input file in each pass, before commencing with the next pass.
  62 .Pp
  63 Before working on a file
  64 .Ar name
  65 .Nm
  66 first checks for the existence of the file
  67 .Ar name.ctm .
  68 If this file exists,
  69 .Nm
  70 works on it instead.
  71 .Pp
  72 Pass 1 will verify that the input file is OK.  The syntax, the data
  73 and the global MD5 checksum will be checked.  If any of these fail,
  74 .Nm
  75 will simply reject the input file.
  76 .Pp
  77 Pass 2 will validate that the directory tree is in the state expected by
  78 the CTM delta.  This is done by looking for files and directories which
  79 should/should not exist and by checking the MD5 checksums of files.
  80 .Pp
  81 If a
  82 .Ar backup-file
  83 had been specified using the
  84 .Fl B
  85 option, all files that would be modified by this
  86 .Nm
  87 invocation are backed up
  88 to this file using the archiver command specified by the
  89 .Fl t
  90 option.  The default archiver command is
  91 .Nm "tar -rf %s -T -" .
  92 .Pp
  93 Pass 3 will actually apply the delta.
  94 .Pp
  95 The list of files that would be modified by
  96 .Nm
  97 is subject to filtering regular expressions specified
  98 using the
  99 .Fl e
 100 and
 101 .Fl x
 102 options.
 103 The
 104 .Fl e
 105 and
 106 .Fl x
 107 options are applied in order of appearance on the command line.  The last
 108 filter that matched a given file name determines whether the file would be
 109 operated on or left alone by
 110 .Nm .
 111 .Pp
 112 The
 113 .Nm
 114 utility
 115 will extract the file hierarchy below its working directory.  Absolute
 116 filenames or filenames containing references through
 117 .Sq Pa .\&
 118 and
 119 .Sq Pa ..\&
 120 are explicitly prohibited as a security measure.
 121 .Ss Options
 122 .Bl -tag -width indent
 123 .It Fl b Ar basedir
 124 Prepend the path
 125 .Ar basedir
 126 to every filename.
 127 .It Fl B Ar backup-file
 128 Backup all files that would be modified by this CTM run to
 129 .Ar backup-file .
 130 If any filters are specified using the
 131 .Fl e
 132 and
 133 .Fl x
 134 options, then the final set of files backed up are those that would be
 135 modified by CTM after the filters are applied.
 136 .It Fl c
 137 Check it out, don't do anything.
 138 .It Fl e Ar regular_expression
 139 Match each name in the CTM file against
 140 .Ar regular_expression ,
 141 and if it matches process the file, otherwise leave it alone.  There may be
 142 any number of these options.  Use of this option disables the
 143 .Pa .ctm_status
 144 sequence number checks.  For example, the expression
 145 .Ic ^usr.sbin/ctm
 146 for example, will select the
 147 .Pa usr.sbin/ctm
 148 source directory and all pathnames under it.
 149 .Pp
 150 Pathnames can be disabled from being considered by CTM using the
 151 .Fl x
 152 option.
 153 .It Fl F
 154 Force.
 155 .It Fl k
 156 Keep files and directories and don't remove them even if the CTM file
 157 specifies they are to be removed.  If the
 158 .Fl B
 159 option is specified, these files and directories will not be backed up.
 160 .It Fl l
 161 List files that would be modified by this invocation of CTM and the
 162 actions that would be performed on them.  Use of the
 163 .Fl l
 164 option disables the
 165 .Pa .ctm_status
 166 checks and integrity checks on the source tree being operated on.  The
 167 .Fl l
 168 option can be combined with the
 169 .Fl e
 170 and
 171 .Fl x
 172 options to determine which files would be modified by the given set of
 173 command line options.
 174 .It Fl q
 175 Tell us less.
 176 .It Fl t Ar tar-command
 177 Use
 178 .Ar tar-command
 179 instead of the default archiver
 180 .Nm tar .
 181 This option takes effect only if a backup file had been specified using the
 182 .Fl B
 183 option.  A %s in the tar command will be replaced by the name of the backup
 184 file.
 185 .It Fl T Ar tmpdir
 186 Put temporary files under
 187 .Ar tmpdir .
 188 .It Fl u
 189 Set modification time of created and modified files to the CTM delta
 190 creation time.
 191 .It Fl v
 192 Tell us more.
 193 .It Fl V Ar level
 194 Tell us more.
 195 .Ar Level
 196 is the level of verbosity.
 197 .It Fl x Ar regular_expression
 198 Match each name in the CTM file against
 199 .Ar regular_expression
 200 and if it matches, leave the file alone.  There may be any number of these
 201 options.  Use of this option disables the
 202 .Pa .ctm_status
 203 sequence number checks.
 204 .Pp
 205 Pathnames can be selected for CTM's consideration using the
 206 .Fl e
 207 option.
 208 .El
 209 .Sh SECURITY
 210 On its own, CTM is an insecure protocol
 211 - there is no authentication performed that the
 212 changes applied to the source code were sent by a
 213 trusted party, and so care should be taken if the
 214 CTM deltas are obtained via an unauthenticated
 215 medium such as regular email.
 216 It is a relatively simple matter for an attacker
 217 to forge a CTM delta to replace or precede the
 218 legitimate one and insert malicious code into your
 219 source tree.
 220 If the legitimate delta is somehow prevented from
 221 arriving, this will go unnoticed until a later
 222 delta attempts to touch the same file, at which
 223 point the MD5 checksum will fail.
 224 .Pp
 225 To remedy this insecurity, CTM pieces generated by
 226 FreeBSD.org are cryptographically signed in a
 227 format compatible with the GNU Privacy Guard
 228 utility, available in /usr/ports/security/gpg, and
 229 the Pretty Good Privacy v5 utility,
 230 /usr/ports/security/pgp5.
 231 The relevant public key can be obtained by
 232 fingering ctm@FreeBSD.org.
 233 .Pp
 234 CTM deltas which are thus signed cannot be
 235 undetectably altered by an attacker.
 236 Therefore it is recommended that you make use of
 237 GPG or PGP5 to verify the signatures if you
 238 receive your CTM deltas via email.
 239 .Sh ENVIRONMENT
 240 .Ev TMPDIR ,
 241 if set to a pathname, will cause ctm to use that pathname
 242 as the location of temporary file.
 243 See
 244 .Xr tempnam 3 ,
 245 for more details on this.
 246 The same effect may be achieved with the
 247 .Fl T
 248 flag.
 249 .Sh FILES
 250 .Pa .ctm_status
 251 contains the sequence number of the last CTM delta applied.  Changing
 252 or removing this file will greatly confuse
 253 .Nm .
 254 .Pp
 255 Using the
 256 .Fl e
 257 and
 258 .Fl x
 259 options can update a partial subset of the source tree and causes sources
 260 to be in an inconsistent state.  It is assumed that you know what you are
 261 doing when you use these options.
 262 .Sh EXAMPLES
 263 .Bd -literal
 264 cd ~cvs
 265 /usr/sbin/ctm ~ctm/cvs-*
 266 .Ed
 267 .Pp
 268 To extract and patch all sources under `lib'
 269 .Bd -literal
 270 cd ~/lib-srcs
 271 /usr/sbin/ctm -e '^lib' ~ctm/src-cur*
 272 .Ed
 273 .Sh DIAGNOSTICS
 274 Numerous messages, hopefully self-explanatory.  The
 275 .Dq noise level
 276 can be adjusted with the
 277 .Fl q ,
 278 .Fl v
 279 and
 280 .Fl V
 281 options.
 282 .Sh SEE ALSO
 283 .Xr ctm_rmail 1 ,
 284 .Xr ctm 5
 285 .Sh HISTORY
 286 Initial trials were run during the work on
 287 .Fx 1.1.5 ,
 288 and many bugs and
 289 methods were hashed out.
 290 .Pp
 291 The
 292 .Nm
 293 command appeared in
 294 .Fx 2.1 .
 295 .Sh AUTHORS
 296 The CTM system has been designed and implemented by
 297 .An Poul-Henning Kamp
 298 .Aq phk@FreeBSD.org .
 299 .Pp
 300 .An Joerg Wunsch
 301 .Aq joerg@FreeBSD.org
 302 wrote this man-page.