Skip to content

Commit 13b454d

Browse files
DuncaenDuncaen
committed
data: add xbps.hook manpage
1 parent f1b2093 commit 13b454d

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
lines changed

‎data/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ all:
1313
install:
1414
install -d $(DESTDIR)$(MANDIR)/man5
1515
install -m644 xbps.d.5 $(DESTDIR)$(MANDIR)/man5
16+
install -m644 xbps.hook.5 $(DESTDIR)$(MANDIR)/man5
1617
install -d $(DESTDIR)$(MANDIR)/man7
1718
install -m644 xbps.7 $(DESTDIR)$(MANDIR)/man7
1819
install -d $(DESTDIR)$(PKGCONFIGDIR)

‎data/xbps.hook.5‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
.Dd December 22, 2025
2+
.Dt XBPS.HOOK 5
3+
.Os
4+
.Sh NAME
5+
.Nm xbps.hook
6+
.Nd XBPS hook configuration
7+
.Sh SYNOPSIS
8+
.Bl -item -compact
9+
.It
10+
/etc/xbps.d/hooks/*.hook
11+
.It
12+
/usr/share/xbps.d/hooks/*.hook
13+
.El
14+
.Sh DESCRIPTION
15+
The
16+
.Nm
17+
files are
18+
.So .ini Sc Ns -style
19+
configuration files to define hooks that execute commands at certain points of
20+
the xbps transactions
21+
.Po
22+
package updates,
23+
installs,
24+
and removals.
25+
.Pc
26+
.Pp
27+
Comments can be put anywhere in the file
28+
and using hashmarks
29+
.Pq Sq # ,
30+
or
31+
semi-colons
32+
.Pq Sq \&; ,
33+
and are continued to the end of the line.
34+
.Sh [HOOK] SECTION OPTIONS
35+
The
36+
.Ic Hook
37+
section is required and defines when the hook is executed and the command that
38+
is being executed as part of the hook.
39+
.Bl -tag -width -x
40+
.It Sy Name = Ar name
41+
Set the hook name used for logging.
42+
.It Ic When = Ar option ...
43+
Defines when the hook is executed.
44+
The following values are supported
45+
and multiple values can be set by
46+
separating them with a space or defining
47+
the
48+
.Sy When
49+
option multiple times.
50+
Valid options are:
51+
.Bl -tag -width -x
52+
.It Ic PreTransaction
53+
Before all packages are installed,
54+
updated,
55+
or removed.
56+
.It Ic PostTransaction
57+
After all packages are installed,
58+
updated,
59+
or removed.
60+
.El
61+
.It Sy Exec = Ar command Op Ar args ...
62+
Command that is executed.
63+
The
64+
.Ar command
65+
and
66+
.Ar args
67+
are split into words according to
68+
.Sx WORD SPLITTING .
69+
.El
70+
.Sh [MATCH] SECTION OPTIONS
71+
A hook is executed if it's
72+
.Ic Match
73+
section matches the current transaction.
74+
.Bl -tag -width -x
75+
.It Ic Package = Ar pkgname | Ar pkgpattern
76+
Matches if
77+
.Ar pkgname
78+
or packages matching
79+
.Ar pkgpattern
80+
are installed,
81+
updated,
82+
removed,
83+
reinstalled,
84+
or configured in the transaction.
85+
.It Ic PackageInstall = Ar pkgname | Ar pkgpattern
86+
Matches if
87+
.Ar pkgname
88+
or packages matching
89+
.Ar pkgpattern
90+
are installed in the transaction.
91+
.It Ic PackageUpdate = Ar pkgname | Ar pkgpattern
92+
Matches if
93+
.Ar pkgname
94+
or packages matching
95+
.Ar pkgpattern
96+
are updated in the transaction.
97+
.It Ic PackageRemove = Ar pkgname | Ar pkgpattern
98+
Matches if
99+
.Ar pkgname
100+
or packages matching
101+
.Ar pkgpattern
102+
are removed in the transaction.
103+
.It Ic PackageReinstall = Ar pkgname | Ar pkgpattern
104+
Matches if
105+
.Ar pkgname
106+
or packages matching
107+
.Ar pkgpattern
108+
are reinstalled in the transaction.
109+
.It Ic PackageConfigure = Ar pkgname | Ar pkgpattern
110+
Matches if
111+
.Ar pkgname
112+
or packages matching
113+
.Ar pkgpattern
114+
are configured in the transaction.
115+
.It Ic Path = Ar path | Ar pattern
116+
Matches if
117+
.Ar path
118+
or paths matching
119+
.Ar pattern
120+
are created,
121+
modified,
122+
or deleted.
123+
.It Ic PathCreated = Ar path | Ar pattern
124+
Matches if
125+
.Ar path
126+
or paths matching
127+
.Ar pattern
128+
are created in the transaction.
129+
.It Ic PathModified = Ar path | Ar pattern
130+
Matches if
131+
.Ar path
132+
or paths matching
133+
.Ar pattern
134+
are modified in the transaction.
135+
.It Ic PathDeleted = Ar path | Ar pattern
136+
Matches if
137+
.Ar path
138+
or paths matching
139+
.Ar pattern
140+
are deleted in the transaction.
141+
.El
142+
.Sh WORD SPLITTING
143+
Options which support multiple free text values will be split into separate
144+
words.
145+
The word boundaries are spaces
146+
.Pq Sq \~
147+
and tabs
148+
.Pq Sq \et .
149+
.Pp
150+
If a word contains a literal space
151+
.Pq Sq \~
152+
or tab
153+
.Pq Sq \et ,
154+
use a backslash
155+
.Pq Sq \e
156+
to escape the character.
157+
.Sh EXAMPLES
158+
The following example restarts the
159+
.Ic sshd
160+
service after the
161+
.Ic ssh
162+
package was updated.
163+
.Bd -literal -offset indent
164+
[Hook]
165+
Name = Restart sshd.
166+
When = PostTransaction
167+
Exec = sv restart /var/service/sshd
168+
169+
[Match]
170+
PackageUpdate = ssh
171+
.Ed
172+
.Pp
173+
This example hook will sign the
174+
.Pa systemd-bootx64.efi
175+
file whenever it is updated or installed.
176+
.Bd -literal -offset indent
177+
[Hook]
178+
Name = Sign the bootloader file.
179+
When = PostTransaction
180+
Exec = sbsign --key /etc/kernel/secure-boot.key.pem \e
181+
--cert /etc/kernel/secure-boot.cert.pem \e
182+
--output /usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed \e
183+
/usr/lib/systemd/boot/efi/systemd-bootx64.efi
184+
185+
[Match]
186+
PathModified = /usr/lib/systemd/boot/efi/systemd-bootx64.efi
187+
.Ed

0 commit comments

Comments
 (0)