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