sbin/rcorder/rcorder.8

   1 .\"     $NetBSD: rcorder.8,v 1.3 2000/07/17 14:16:22 mrg Exp $
   2 .\"
   3 .\" Copyright (c) 1998
   4 .\"     Perry E. Metzger.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgment:
  16 .\"     This product includes software developed for the NetBSD Project
  17 .\"     by Perry E. Metzger.
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd September 8, 2020
  35 .Dt RCORDER 8
  36 .Os
  37 .Sh NAME
  38 .Nm rcorder
  39 .Nd print a dependency ordering of interdependent files
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl gp
  43 .Op Fl k Ar keep
  44 .Op Fl s Ar skip
  45 .Ar
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 utility is designed to print out a dependency ordering of a set of
  50 interdependent files.
  51 Typically it is used to find an execution
  52 sequence for a set of shell scripts in which certain files must be
  53 executed before others.
  54 .Pp
  55 Each file passed to
  56 .Nm
  57 must be annotated with special lines (which look like comments to the
  58 shell) which indicate the dependencies the files have upon certain
  59 points in the sequence, known as
  60 .Dq conditions ,
  61 and which indicate, for each file, which
  62 .Dq conditions
  63 may be expected to be filled by that file.
  64 .Pp
  65 Within each file, a block containing a series of
  66 .Ql REQUIRE ,
  67 .Ql PROVIDE ,
  68 .Ql BEFORE
  69 and
  70 .Ql KEYWORD
  71 lines must appear.
  72 The format of the lines is rigid.
  73 Each line must begin with a single
  74 .Ql # ,
  75 followed by a single space, followed by
  76 .Ql PROVIDE\&: ,
  77 .Ql REQUIRE\&: ,
  78 .Ql BEFORE\&: ,
  79 or
  80 .Ql KEYWORD\&: .
  81 No deviation is permitted.
  82 Each dependency line is then followed by a series of conditions,
  83 separated by whitespace.
  84 Multiple
  85 .Ql PROVIDE ,
  86 .Ql REQUIRE ,
  87 .Ql BEFORE
  88 and
  89 .Ql KEYWORD
  90 lines may appear, but all such lines must appear in a sequence without
  91 any intervening lines, as once a line that does not follow the format
  92 is reached, parsing stops.
  93 .\" Note that for historical reasons REQUIRES, PROVIDES, and KEYWORDS
  94 .\" are also accepted in addition to the above, but not documented so
  95 .\" that they can be deprecated at some point in the future.
  96 .Pp
  97 The options are as follows:
  98 .Bl -tag -width "-k keep"
  99 .It Fl g
 100 Produce a GraphViz (.dot) of the complete dependency graph instead of
 101 plaintext calling order list.
 102 .It Fl k Ar keep
 103 Add the specified keyword to the
 104 .Dq "keep list" .
 105 If any
 106 .Fl k
 107 option is given, only those files containing the matching keyword are listed.
 108 This option can be specified multiple times.
 109 .It Fl p
 110 Generate ordering suitable for parallel startup, placing files that can be
 111 executed simultaneously on the same line.
 112 .It Fl s Ar skip
 113 Add the specified keyword to the
 114 .Dq "skip list" .
 115 If any
 116 .Fl s
 117 option is given, files containing the matching keyword are not listed.
 118 This option can be specified multiple times.
 119 .El
 120 .Pp
 121 An example block follows:
 122 .Bd -literal -offset indent
 123 # REQUIRE: networking syslog
 124 # REQUIRE: usr
 125 # PROVIDE: dns nscd
 126 .Ed
 127 .Pp
 128 This block states that the file in which it appears depends upon the
 129 .Ql networking ,
 130 .Ql syslog ,
 131 and
 132 .Ql usr
 133 conditions, and provides the
 134 .Ql dns
 135 and
 136 .Ql nscd
 137 conditions.
 138 .Pp
 139 A file may contain zero
 140 .Ql PROVIDE
 141 lines, in which case it provides no conditions, and may contain zero
 142 .Ql REQUIRE
 143 lines, in which case it has no dependencies.
 144 There must be at least one file with no dependencies in the set of
 145 arguments passed to
 146 .Nm
 147 in order for it to find a starting place in the dependency ordering.
 148 .Sh KEYWORDS
 149 There are several
 150 .Em KEYWORDs
 151 in use:
 152 .Bl -tag -width "shutdown" -offset indent
 153 .It Sy firstboot , nojail , nojailvnet , nostart
 154 Used by
 155 .Xr rc 8 .
 156 .It Sy resume
 157 Used by
 158 .Nm /etc/rc.resume
 159 (see
 160 .Xr acpiconf 8 )
 161 .It Sy shutdown
 162 Used by
 163 .Xr rc.shutdown 8 .
 164 .El
 165 .Sh EXAMPLES
 166 Print the dependency ordering of the services from the base system and
 167 .Xr ports 7 :
 168 .Bd -literal -offset indent
 169 $ rcorder /etc/rc.d/* /usr/local/etc/rc.d/*
 170 .Ed
 171 .Pp
 172 Count the number of services in the base system, which specify the
 173 .Sy shutdown
 174 keyword, while skipping those with
 175 .Sy firstboot
 176 and
 177 .Sy nojailvnet :
 178 .Bd -literal -offset indent
 179 $ rcorder -k nostart -s firstboot -s nojailvnet /etc/rc.d/*  | wc -l
 180        3
 181 .Ed
 182 .Sh DIAGNOSTICS
 183 The
 184 .Nm
 185 utility may print one of the following error messages and exit with a non-zero
 186 status if it encounters an error while processing the file list.
 187 .Bl -diag
 188 .It "Requirement %s in file %s has no providers."
 189 No file has a
 190 .Ql PROVIDE
 191 line corresponding to a condition present in a
 192 .Ql REQUIRE
 193 line in another file.
 194 .It "Circular dependency on provision %s in file %s."
 195 A set of files has a circular dependency which was detected while
 196 processing the stated condition.
 197 Loop visualization follows this message.
 198 .It "Circular dependency on file %s."
 199 A set of files has a circular dependency which was detected while
 200 processing the stated file.
 201 .It "%s was seen in circular dependencies for %d times."
 202 Each node that was a part of circular dependency loops reports total number of
 203 such encounters.
 204 Start with files having biggest counter when fighting with broken dependencies.
 205 .El
 206 .Sh DIAGNOSTICS WITH GRAPHVIZ
 207 Direct dependency is drawn with solid line,
 208 .Ql BEFORE
 209 dependency is drawn as a dashed line.
 210 Each node of a graph represents an item from
 211 .Ql PROVIDE
 212 lines.
 213 In case there are more than one file providing an item, a list of filenames
 214 shortened with
 215 .Xr basename 3
 216 is shown.
 217 Shortened filenames are also shown in case
 218 .Ql PROVIDE
 219 item does not match file name.
 220 .Pp
 221 Edges and nodes where circular dependencies were detected are drawn bold red.
 222 If a file has an item in
 223 .Ql REQUIRE
 224 or in
 225 .Ql BEFORE
 226 that could not be provided,
 227 this missing provider and the requirement will be drawn bold red as well.
 228 .Sh SEE ALSO
 229 .Xr acpiconf 8 ,
 230 .Xr rc 8 ,
 231 .Xr rc.shutdown 8 ,
 232 .Xr service 8
 233 .Sh HISTORY
 234 The
 235 .Nm
 236 utility appeared in
 237 .Nx 1.5 .
 238 .Nm
 239 utility first appeared in
 240 .Fx 5.0 .
 241 .Sh AUTHORS
 242 .An -nosplit
 243 Written by
 244 .An Perry E. Metzger Aq Mt perry@piermont.com
 245 and
 246 .An Matthew R. Green Aq Mt mrg@eterna.com.au .
 247 .Sh BUGS
 248 The
 249 .Ql REQUIRE
 250 keyword is misleading:
 251 It does not describe which daemons have to be running before a script
 252 will be started.
 253 It describes which scripts must be placed before it in
 254 the dependency ordering.
 255 For example,
 256 if your script has a
 257 .Ql REQUIRE
 258 on
 259 .Ql sshd ,
 260 it means the script must be placed after the
 261 .Ql sshd
 262 script in the dependency ordering,
 263 not necessarily that it requires
 264 .Nm sshd
 265 to be started or enabled.