From: Evan Silberman Subject: Re: [patch] rdist.1 partial rewrite To: Jason McIntyre Cc: tech@openbsd.org Date: Tue, 05 Nov 2024 10:13:48 -0800 Jason McIntyre wrote: > On Mon, Nov 04, 2024 at 02:26:12PM -0800, Evan Silberman wrote: > > I was just going to come in here and zap some unnecessary \*(Lt but I > > got a bit carried away. This patch reorganizes and hopefully improves > > the DISTFILES section of rdist.1, which was a bit hard to follow and > > presented commands and subcommands in a weird way. This organizes the > > material in a way more familiar from other manual pages describing > > command languages. > > > > Hopefully it's also accurate; I'm not actually an rdist user I just > > got sniped. I tried not to freelance too much and retained much of the > > previous material even if some of it seems a bit vague. And I still > > zapped the unnecessary \*(Gt and \*(Lt. > > > > Evan > > > > hi. the patch does not apply cleanly - can you retry (maybe attach it)? > jmc Weird. Attached. diff /usr/src commit - 22896994b80273a9a0d8a8e5bb8286e98e08922c path + /usr/src blob - 0a9734d48e3b26211655841b94e946b0a5e9bef1 file + usr.bin/rdist/rdist.1 --- usr.bin/rdist/rdist.1 +++ usr.bin/rdist/rdist.1 @@ -119,7 +119,7 @@ Otherwise, .Nm will run the command: .Bd -literal -offset indent -ssh \*(Lthost\*(Gt -l \*(Ltlogin_name\*(Gt rdistd -S +ssh -l rdistd -S .Ed .Pp .Ar host @@ -140,7 +140,7 @@ option was specified, .Nm will attempt to run the command: .Bd -literal -offset indent -\*(Ltrdistd path\*(Gt -S + -S .Ed .Pp If no @@ -180,7 +180,7 @@ $ rdist -c name ... [login@]host[:dest] .Pp The equivalent distfile is as follows: .Bd -literal -offset indent -( name ... ) -\*(Gt [login@]host +( name ... ) -> [login@]host install [dest] ; .Ed .It Fl D @@ -410,181 +410,243 @@ Print version information and exit. .Sh DISTFILES The .Pa distfile -contains a sequence of entries that specify the files +contains a sequence of commands that specify the files to be copied, the destination hosts, and what operations to perform to do the updating. -Each entry has one of the following formats. -.Bd -literal -offset indent -\*(Ltvariable name\*(Gt = \*(Ltname list\*(Gt -[ label: ] \*(Ltsource list\*(Gt -\*(Gt \*(Ltdestination list\*(Gt \*(Ltcommand list\*(Gt -[ label: ] \*(Ltsource list\*(Gt :: \*(Lttimestamp file\*(Gt \*(Ltcommand list\*(Gt -.Ed .Pp -The first format is used for defining variables. -The second format is used for distributing files to other hosts. -The third format is used for making lists of files that have been changed -since some given date. -The -.Ar source list -specifies a list of files and/or directories on the local host which are to -be used as the master copy for distribution. -The -.Ar destination list -is the list of hosts to which these files are to be copied. -Each file in the source list is added to a list of changes if the file -is out of date on the host which is being updated (second format) or -the file is newer than the -.Ar timestamp file -(third format). -.Pp -Newlines, tabs, and blanks are only used as separators and are -otherwise ignored. +Newlines, tabs, and blanks in a +.Pa distfile +are only used as separators and are otherwise ignored. Comments begin with .Sq # and end with a newline. .Pp -Variables to be expanded begin with -.Sq $ -followed by one character or a name enclosed in curly braces -(see the examples at the end). +The commands in the +.Pa distfile +operate on +.Ar namelist Ns s , +which can be given in the following formats: +.Bl -tag -width Ds -offset indent +.It Ar name +A single +.Ar name . +.It Cm \&( Oo Ar name ... Oc Cm \&) +Zero or more +.Ar name Ns s +separated by whitespace, enclosed by parentheses. +.It Ar nl1 Cm - Ar nl2 +All names in list +.Ar nl1 +not present in list +.Ar nl2 . +.It Ar nl1 Cm + Ar nl2 +The union of +.Ar nl1 +and +.Ar nl2 . +.It Ar nl1 & Ar nl2 +The intersection of +.Ar nl1 +and +.Ar nl2 . +.El .Pp -Labels are optional. -They are used to identify a specific command to execute -(for example, allowing an update of a subset of a repository). -.Pp -The source and destination lists have the following format: -.Bd -literal -offset indent -\*(Ltname\*(Gt -.Ed -or -.Bd -literal -compact -offset indent -`(' \*(Ltzero or more names separated by whitespace\*(Gt `)' -.Ed -.Pp -These simple lists can be modified by using one level of set addition, -subtraction, or intersection like this: -.Pp -.Dl list - list -or -.Dl list + list -or -.Dl list & list -.Pp -If additional modifications are needed (e.g.\& -.Do -all servers and client machines except for the OSF/1 machines -.Dc ) -then the list will have to be explicitly constructed in steps using -.Dq temporary -variables. -.Pp -The shell meta-characters `[', `]', `{', `}', `*', and `?' +Each +.Ar name +in a +.Ar namelist +is subject to expansion. +The shell meta-characters +.Sq \&[ , +.Sq \&] , +.Sq \&{ , +.Sq \&} , +.Sq * , +and +.Sq \&? are recognized and expanded (on the local host only) in the same way as .Xr ksh 1 . They can be escaped with a backslash. -The `~' character is also expanded in the same way as +The +.Sq ~ +character is also expanded in the same way as .Xr ksh 1 but is expanded separately on the local and destination hosts. When the -.Fl o Ar whole -option is used with a file name that begins with `~', everything except the -home directory is appended to the destination name. -File names which do not begin with `/' or `~' use the destination user's +.Fl o Cm whole +option is used with a file name that begins with +.Sq \&~ , +everything except the home directory is appended to the destination name. +File names which do not begin with +.Sq / +or +.Sq ~ +use the destination user's home directory as the root directory for the rest of the file name. +.Cm ${ Ns Ar var Ns Cm \&} +is expanded to the list assigned to +.Ar var +.Pq see below . .Pp -The command list consists of zero or more commands of the following -format: -.Bl -column "except_pat" "" "opt_dest_name" ";" -offset indent -.It install Ta \*(Ltoptions\*(Gt Ta opt_dest_name Ta ; -.It notify Ta \*(Ltname list\*(Gt Ta "" Ta ; -.It except Ta \*(Ltname list\*(Gt Ta "" Ta ; -.It except_pat Ta \*(Ltpattern list\*(Gt Ta "" Ta ; -.It special Ta \*(Ltname list\*(Gt Ta string Ta ; -.It cmdspecial Ta \*(Ltname list\*(Gt Ta string Ta ; -.El -.Pp -The -.Cm install -command is used to copy out-of-date files and/or directories. -Each source file is copied to each host in the destination list. -Directories are recursively copied in the same way. -.Ar opt_dest_name -is an optional parameter to rename files. +Each command in +.Pa distfile +has one of the following formats. +.Bl -tag -width Ds +.It Ar var Cm = Ar namelist +Assign +.Ar namelist +to the variable +.Ar var . +.It Oo Ar label Ns Cm \&: Oc Ar sources Cm -> Ar destinations Op Ar subcommands +Apply +.Ar subcommands +to the local files in the namelist +.Ar sources +and the remote hosts in the namelist +.Ar destinations . +If a hostname in +.Ar destinations +ends in a +.Sq + +(plus sign), +then the plus +is stripped off and NFS checks are disabled. +This is equivalent to disabling the +.Fl o Cm chknfs +option just for this one host. If no -.Cm install -command appears in the command list or the destination name is not specified, -the source file name is used. +.Ic install +command is present in +.Ar subcommands , +each out-of-date file in +.Ar sources +will be copied to each host in +.Ar destinations . +The login name used on the destination host is the same as the local host +unless the destination name is of the format +.Ar login Ns Cm @ Ns Ar host , +in which case +.Ar login +is used. +.It Oo Ar label Ns Cm \&: Oc Ar sources Cm \&:\&: Ar timestampfile Op Ar subcommands +Apply +.Ar subcommands +to the local files in the namelist +.Ar sources +which have a later modification time than the local file +.Ar timestampfile . +Any +.Ic install +.Ar subcommands +are ignored. +The +.Ic special +and +.Ic cmdspecial +commands are executed on the local host. +.El +.Pp +A command can be prefixed by a +.Ar label , +which can be given as a +.Ar name +argument to +.Nm +as described above. +.Pp +The +.Ar subcommands +are one or more of the following: +.Bl -tag -width cmdspecial +.It Ic install Oo Fl o Ar distopts Oc Oo Ar destname Oc Cm \&; +Copy each file in +.Ar sources +to each host in +.Ar destinations +where the file is out-of-date. +If +.Ar destname +is given and there is more than one local file named in +.Ar sources , +each local file will be copied into the directory +.Ar destname +on each destination host. +If +.Ar destname +is given and only one file is named in +.Ar sources , +the file is copied to +.Ar destname +on each destination host. +Local directories in +.Ar sources +are copied recursively to their destination. Directories in the path name will be created if they do not exist on the remote host. +.Pp The .Fl o Ar distopts -option as specified above has the same semantics as -on the command line except +option has the same semantics as on the command line except .Ar distopts -only applies to the files in the source list. -The login name used on the destination host is the same as the local host -unless the destination name is of the format -.Dq login@host . -.Pp -The -.Cm notify -command is used to mail the list of files updated (and any errors -that may have occurred) to the listed names. -If no `@' appears in the name, the destination host is appended to -the name -(e.g. name1@host, name2@host, ...). -.Pp -The -.Cm except -command is used to update all of the files in the source list -.Sy except -for the files listed in -.Ar name list . +only applies to the files in +.Ar sources . +.It Ic notify Ar addresses Cm \&; +Mail a list of files updated and any errors that may have occurred +to each address in the namelist +.Ar addresses . +If no +.Sq @ +appears in an address in +.Ar addresses , +the destination host is used as the host part of that address. +.It Ic except Ar names Cm \&; +Exclude the files in +.Ar sources +that are listed in +.Ar names +from processing by the command. This is usually used to copy everything in a directory except certain files. -.Pp -The -.Cm except_pat -command is like the -.Cm except -command except that -.Ar pattern list -is a list of basic regular expressions -(see -.Xr re_format 7 -for details). -If one of the patterns matches some string within a file name, that file will -be ignored. +.It Ic except_pat Ar patterns Cm \&; +Exclude any files in +.Ar sources +that match any of the basic regular expressions in namelist +.Ar patterns +from processing by the command. Note that since `\e' is a quote character, it must be doubled to become part of the regular expression. Variables are expanded in .Ar pattern list but not shell file pattern matching characters. To include a `$', it must be escaped with `\e'. +.It Ic special Oo Ar files Oc Cm \&" Ns Ar command Ns Cm \&" .Pp -The -.Cm special -command is used to specify +Execute the shell commands in +.Ar command +on the remote host using .Xr sh 1 -commands that are to be executed on the remote host after the file in -.Ar name list +after each file in +.Ar files is updated or installed. -If the -.Ar name list +If +.Ar files is omitted then the shell commands will be executed for every file updated or installed. -.Ar string -starts and ends with `"' and can cross multiple lines in +.Ar command +must be surrounded by +.Sq \&" +characters and can cross multiple lines in .Pa distfile . -Multiple commands to the shell should be separated by `;'. -Commands are executed in the user's home directory on the host +Multiple commands to the shell should be separated by +.Sq \&; . +Shell commands are executed in the user's home directory on the host being updated. The -.Cm special -command can be used, for example, to rebuild private databases +.Ic special +subcommand can be used, for example, to rebuild private databases after a program has been updated. The following environment variables are set for each -.Cm special -command: +.Ic special +subcommand: .Pp .Bl -tag -width "BASEFILE" -offset 3n -compact .It Ev FILE @@ -594,12 +656,10 @@ The full pathname of the remote file that was just upd .It BASEFILE The basename of the remote file that was just updated. .El -.Pp -The -.Cm cmdspecial -command is similar to the -.Cm special -command, except it is executed only when the entire command is completed +.It Ic cmdspecial Oo Ar files Oc \&" Ns Ar command Ns Cm \&" +Similar to the +.Ic special +subcommand, except it is executed only when the entire command is completed instead of after each file is updated. The list of files is placed in the .Ev FILES @@ -609,15 +669,7 @@ Each file name in is separated by a .Sq :\& (colon). -.Pp -If a hostname ends in a -.Sq + -(plus sign), -then the plus -is stripped off and NFS checks are disabled. -This is equivalent to disabling the -.Fl o Ar chknfs -option just for this one host. +.El .Sh MESSAGE LOGGING .Nm uses a collection of predefined message @@ -750,20 +802,20 @@ FILES = ( /bin /lib /usr/bin /usr/games EXLIB = ( Mail.rc aliases aliases.db crontab dshrc sendmail.cf sendmail.hf sendmail.st uucp vfont ) -${FILES} -\*(Gt ${HOSTS} +${FILES} -> ${HOSTS} install -oremove,chknfs ; except /usr/lib/${EXLIB} ; except /usr/games/lib ; special /usr/lib/sendmail "/usr/lib/sendmail -bi" ; srcs: -/usr/src/bin -\*(Gt arpa +/usr/src/bin -> arpa except_pat ( \e\e.o\e$ /SCCS\e$ ) ; IMAGEN = (ips dviimp catdvi) imagen: -/usr/local/${IMAGEN} -\*(Gt arpa +/usr/local/${IMAGEN} -> arpa install /usr/local/lib ; notify ralph ;