rpm  5.4.15
triggers
Go to the documentation of this file.
1 /*! \page triggers Trigger scriptlets
2 
3 Triggers provide a well-defined method for packages to interact with one
4 another at package install and uninstall time. They are an extension
5 of the normal installation scripts (i.e. %pre) which allows one package
6 (the "source" of the trigger package [which I often think of as the
7 "triggered package"]) to execute an action when the installation status
8 of another package (the "target" of the trigger) changes.
9 
10 \subsection triggers_example A Simple Example
11 
12 Say the package "mymailer" needs an /etc/mymailer/mailer symlink which points
13 to the mail transport agent to use. If sendmail is installed, the link should
14 point to /usr/bin/sendmail, but it vmail is installed, the link should
15 instead point to /usr/bin/vmail. If both packages are present, we don't care
16 where the link points (realistically, sendmail and vmail should conflict
17 with one another), while if neither package is installed the link should
18 not exist at all.
19 
20 This can be accomplished by mymailer providing trigger scripts which
21 move the symlink when any of the following occurs:
22 
23 \verbatim
24  1) sendmail is installed
25  2) vmail is installed
26  3) sendmail is removed
27  4) vmail is removed
28 \endverbatim
29 
30 The first two of these scripts would look like this:
31 
32 \verbatim
33  %triggerin -- sendmail
34  ln -sf /usr/bin/sendmail /etc/mymailer/mailer
35 
36  %triggerin -- vmail
37  ln -sf /usr/bin/vmail /etc/mymailer/mailer
38 \endverbatim
39 
40 These are two installation triggers, triggered by one of sendmail or vmail.
41 They are run when:
42 
43 \verbatim
44  1) mymailer is already installed, and sendmail is installed or
45  upgraded
46  2) mymailer is already installed, and vmail is installed or
47  upgraded
48  3) sendmail is already installed, and mymailer is installed or
49  upgraded
50  4) vmail is already installed, and mymailer is installed or
51  upgraded
52 \endverbatim
53 
54 For the upgrading, the strategy is a little different. Rather then
55 setting the link to point to the trigger, the link is set to point to
56 the *other* mailer (if it exists), as follows:
57 
58 \verbatim
59  %triggerun -- sendmail
60  [ $2 = 0 ] || exit 0
61  if [ -f /usr/bin/vmail ]; then
62  ln -sf /usr/bin/vmail /etc/mymailer/mailer
63  else
64  rm -f /etc/mymailer/mailer
65 
66  fi
67 
68  %triggerun -- vmail
69  [ $2 = 0 ] || exit 0
70  if [ -f /usr/bin/sendmail ]; then
71  ln -sf /usr/bin/sendmail /etc/mymailer/mailer
72  else
73  rm -f /etc/mymailer/mailer
74 
75  fi
76 
77  %postun
78  [ $1 = 0 ] && rm -f /etc/mymailer/mailer
79 \endverbatim
80 
81 These trigger scripts get run when:
82 
83 \verbatim
84  1) sendmail is installed, and mymailer is removed
85  2) vmail is installed, and mymailer is removed
86  3) mymailer is installed, and sendmail gets removed
87  4) mymailer is installed, and vmail gets removed
88 \endverbatim
89 
90 The %postun insures that /etc/mymailer/mailer is removed when mymailer
91 is removed (triggers get run at the same time as %preun scripts, so
92 doing this in the %postun is safe). Note that the triggers are testing
93 $2 to see if any action should occur. Recall that the $1 passed to regular
94 scripts contains the number of instances of the package which will be
95 installed when the operation has completed. $1 for triggers is exactly
96 the same -- it is the number of instances of the source (or triggered)
97 package which will remain when the trigger has completed. Similarly, $2
98 is the number of instances of the target package which will remain. In
99 this case, if any of the targets will remain after the uninstall, the
100 trigger doesn't do anything (as it's probably being triggered by an
101 upgrade).
102 
103 \subsection triggers_syntax Trigger Syntax
104 
105 Trigger specifications are of the form:
106 
107 \verbatim
108  %trigger{un|in|postun} [[-n] SUBPKGSUFFIX] [-p PROGRAM] -- TRIGGER
109 \endverbatim
110 
111 The -n and -p arguments are the same as for %post scripts. The
112 TRIGGER portion is syntactically equivalent to a "Requires"
113 specification (version numbers may be used). If multiple items are
114 given (comma separated), the trigger is run when *any* of those
115 conditions becomes true (the , can be read as "or"). For example:
116 
117 \verbatim
118  %triggerin -n package -p /usr/bin/perl -- fileutils > 3.0, perl < 1.2
119  print "I'm in my trigger!\n";
120 \endverbatim
121 
122 Will put a trigger in package 'package' which runs when the installation
123 status of either fileutils > 3.0 or perl < 1.2 is changed. The script will
124 be run through /usr/bin/perl rather then /bin/sh (which is the default).
125 
126 \subsection triggers_unusual An Unusual Case
127 
128 There is one other type of trigger available -- %triggerpostun. These are
129 triggers that are run after their target package has been removed; they will
130 never be run when the package containing the trigger is removed.
131 
132 While this type of trigger is almost never useful, they allow a package to
133 fix errors introduced by the %postun of another package (or by an earlier
134 version of that package).
135 
136 \subsection triggers_order Order of Script Execution
137 
138 For reference, here's the order in which scripts are executed on a single
139 package upgrade:
140 
141 \verbatim
142  all-%pretrans
143  ...
144  any-%triggerprein (%triggerprein from other packages set off by new install)
145  new-%triggerprein
146  new-%pre for new version of package being installed
147  ... (all new files are installed)
148  new-%post for new version of package being installed
149 
150  any-%triggerin (%triggerin from other packages set off by new install)
151  new-%triggerin
152  old-%triggerun
153  any-%triggerun (%triggerun from other packages set off by old uninstall)
154 
155  old-%preun for old version of package being removed
156  ... (all old files are removed)
157  old-%postun for old version of package being removed
158 
159  old-%triggerpostun
160  any-%triggerpostun (%triggerpostun from other packages set off by old un
161  install)
162  ...
163  all-%posttrans
164 \endverbatim
165 */