-
Notifications
You must be signed in to change notification settings - Fork 3
/
overview-jectl.txt
174 lines (133 loc) · 5.7 KB
/
overview-jectl.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
Overview of jectl:
What is it?
jectl is the nexus between poudriere and jail.conf
What is its purpose?
To ease the process of updating jails.
How does it do that?
By using ZFS to manage the underlying jail filesystem, called jail
environments. jectl is to jail environments as bectl is to boot
environments. The concept is the same, but the behavior of jectl is
slightly different.
Prior reading?
It assumed the reader has a prior understanding of poudriere.
See overview-generate-je.txt and overview-zfs-layout.txt as well.
A walkthrough of usage:
See or search MANPAGE in this document for explanation of flags:
% jectl
Run the following before/after jectl commands to see what's happening:
% zfs list -r zroot/JE zroot/JAIL
Generate a ZFS send stream using poudriere-image(8) and generate-je.sh:
% poudriere jail -c -j rew -v 12.0-RELEASE
% poudriere image -t zfs+send -B generate-je.sh -s 1G -j rew -o /home/rew -n stream
[ ... snipped ... ]
[00:00:23] Image available at: /home/rew/stream.full.zfs
Create a jail dataset named klara from the generated ZFS stream:
% cat stream.full.zfs | jectl import klara
Where 'klara' corresponds to a jail defined in jail.conf(5):
path = /$name;
exec.prepare = "jectl mount $name $path";
exec.start = "/bin/sh /etc/rc";
exec.stop = "/bin/sh /etc/rc.shutdown";
klara { }
Check info for klara jail:
% jectl dump klara
Jail name: klara
Environments:
1. Name: default (ACTIVE)
branch: 12.0-RELEASE-p13
version: 1200086
poudriere-jail: rew
Starting and stopping the jail behaves as normal:
% service jail start
Starting jails: klara.
% service jail stop
Stopping jails: klara.
After some amount of time passes..it is time to update.
The dirty work of updating is handed off to poudriere, there are two ways
to do this. One way is to create a new poudriere jail with the desired version:
% poudriere jail -c -j next -v 12.1-RELEASE
And then generate a jail environment using poudriere + generate-je.sh.
Note that passing -t zfs+send+be creates a jail environment only:
% poudriere image -t zfs+send+be -B generate-je.sh -s 1G -j next -o /home/rew -n stream
[ ... snipped ... ]
[00:00:37] Image available at: /home/rew/stream.je.zfs
Import the generated ZFS stream:
% cat stream.je.zfs | jectl import 12.1-RELEASE
Set the active jail environment for the klara jail:
% jectl activate klara 12.1-RELEASE
Check the updated info for klara jail:
% jectl dump klara
Jail name: klara
Environments:
1. Name: default (ACTIVE)
branch: 12.0-RELEASE-p13
version: 1200086
poudriere-jail: rew
2. Name: 12.1-RELEASE
branch: 12.1-RELEASE-p13
version: 1201000
poudriere-jail: next
The next time the klara jail is started, it will be running the newer version of FreeBSD.
Continuing with the example above, here is the second way to update a jail.
Again, the dirty work of updating is deferred to poudriere:
% poudriere jail -u -j next -t 12.2-RELEASE
Once the poudriere jail is updated, generate a jail environment from it:
% poudriere image -t zfs+send+be -B generate-je.sh -s 1G -j next -o /home/rew -n stream
[ ... snipped ... ]
[00:00:21] Image available at: /home/rew/stream.je.zfs
And then import it:
% cat stream.je.zfs | jectl import 12.2-RELEASE
Inspect the imported jail environment:
% jectl dump
[ ... snippped .. ]
Available jail environments:
[ ... snippped .. ]
3. Name: 12.2-RELEASE
branch: 12.2-RELEASE-p15
version: 1202000
poudriere-jail: next
Before updating, check active jail environment of klara:
% jectl dump klara
Jail name: klara
Environments:
[ ... snippped .. ]
2. Name: 12.1-RELEASE (ACTIVE)
branch: 12.1-RELEASE-p13
version: 1201000
poudriere-jail: next
Then update klara jail:
% jectl update klara
Verify that it updated:
% jectl dump klara
Jail name: klara
Environments:
[ ... snippped .. ]
3. Name: 12.2-RELEASE (ACTIVE)
branch: 12.2-RELEASE-p15
version: 1202000
poudriere-jail: next
When jectl does an update, it compares the following properties between
the active jail environment dataset and imported jail environment datasets.
If the jailname, overlaydir, and packagelist are the same; and if the
freebsd_version for the active environment is less than the imported jail
environment, an update is performed. Therefore, if freebsd_version is
not bumped, an update is not recognized. List of properties:
je:version (unused, mentioned for patch updates)
je:poudriere:jailname (name of poudriere jail)
je:poudriere:overlaydir (name of overlay directory used)
je:poudriere:packagelist (name of package list used)
je:poudriere:freebsd_version (output of uname -U => 1301000)
With all that explained, consider the following workflow.
Use the jectl's update subcommand in jail.conf(5):
path = /$name;
exec.prepare = "jectl update $name $path";
exec.start = "/bin/sh /etc/rc";
exec.stop = "/bin/sh /etc/rc.shutdown";
klara { }
Update the poudriere jail, generate a stream, and import it.
% poudriere jail -u -j next -t 13.1-BETA2
% poudriere image -t zfs+send+be -B generate-je.sh -s 1G -j next -o /home/rew -n stream
% cat stream.je.zfs | jectl import 13.1-BETA2
Restart the klara jail:
% service jail restart
Assuming no errors, the klara jail will now be running 13.1-BETA2