This repository has been archived by the owner on Apr 4, 2024. It is now read-only.
/
iocage.8
2098 lines (2098 loc) · 47.9 KB
/
iocage.8
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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.Dd September 12, 2020
.Dt IOCAGE 8
.Os
.Sh NAME
.Nm iocage
.Nd jail manager using ZFS and VNET
.Sh SYNOPSIS
.\" == DEBUG ==
.Nm
.Op Fl D | -debug
.\" == HELP ==
.Nm
.Op Fl -help | Ar SUBCOMMAND Fl -help
.\" == VERSION ==
.Nm
.Op Fl v | -version
.Pp
.\" == ACTIVATE ==
.Nm
.Cm activate
.Ar ZPOOL
.\" == CHROOT ==
.Nm
.Cm chroot
.Ar UUID | NAME
.Op Ar COMMAND
.\" == CLEAN ==
.Nm
.Cm clean
.Op Fl a | -all | Cm dataset_type
.Op Fl b | r | -base | Cm dataset_type
.Op Fl f | -force
.Op Fl j | -jails | Cm dataset_type
.Op Fl t | -template | Cm dataset_type
.\"== CLONE ==
.Nm
.Cm clone
.Ar UUID | NAME Op Ar PROPERTIES
.Op Fl c | -count Ar TEXT
.\" == CONSOLE ==
.Nm
.Cm console
.Op Fl f | -force
.Ar UUID | NAME
.\" == CREATE ==
.Nm
.Cm create
.Op Fl b | -basejail
.Op Fl c | -count Ar TEXT
.Op Fl e | -empty
.Op Fl f | -force
.Op Fl n | -name Ar TEXT
.Op Fl p | -pkglist Ar TEXT
.Op Fl r | -release Ar TEXT
.Op Fl r | -release Cm latest | Cm LATEST
.Op Fl s | -short
.Op Fl t | -template Ar TEXT
.Op Fl B | -clone_basejail
.Op Fl T | -thickjail
.Op Fl u | -uuid | Ar TEXT
.Op Ar PROPERTIES
.\" == DESTROY ==
.Nm
.Cm destroy
.Op Fl R | -recursive
.Op Fl d | -download
.Op Fl f | -force
.Op Fl r | -release
.Ar UUID | NAME
.\" == DF ==
.Nm
.Cm df
.Op Fl H | h | -header
.Op Fl l | -long
.Op Fl s | -sort Ar TEXT
.\" == EXEC ==
.Nm
.Cm exec
.Op Fl f | -force
.Op Fl U | -jail_user Ar NAME
.Op Fl u | -host_user Ar NAME
.Ar UUID | NAME
.Cm -- COMMAND Op Ar ARGS
.\" == EXPORT ==
.Nm
.Cm export
.Ar UUID | NAME
.\" == FETCH ==
.Nm
.Cm fetch
.Op Fl -accept
.Op Fl -noaccept
.Op Fl -plugins Ar OPTIONS
.Op Fl -plugins Fl -official Ar OPTIONS
.Op Fl E | -eol
.Op Fl F | -files
.Op Fl NE | -noeol
.Op Fl NU | -noupdate
.Op Fl NV | -noverify
.Op Fl P | -plugin-file
.Op Fl U | -update
.Op Fl V | -verify
.Op Fl a | -auth
.Op Fl c | -count
.Op Fl d | -root-dir
.Op Fl f | -file
.Op Fl h | -http
.Op Fl n | -name TEXT
.Op Fl p | -password
.Op Fl r | -release | Cm latest | Cm LATEST
.Op Fl s | -server
.Op Fl u | -user
.\" == FSTAB ==
.Nm
.Cm fstab
.Ar JAIL
.Ar FSTAB_STRING
.Op Fl H | h | -header
.Op Fl R | -replace
.Op Fl a | -add | Cm action
.Op Fl e | -edit | Cm action
.Op Fl l | -list
.Op Fl r | -remove | Cm action
.\" == GET ==
.Nm
.Cm get
.Ar PROPERTY
.Ar UUID | NAME
.Op Fl H | h | -header
.Op Fl P | -plugin Op Fl f | -force
.Op Fl a | -all
.Op Fl p | -pool
.Op Fl r | -recursive
.Op Fl s | Cm state
.Op Fl j | Cm JID
.\" == IMPORT ==
.Nm
.Cm import
.Ar UUID | NAME
.\" == LIST ==
.Nm
.Cm list
.Op Fl -http
.Op Fl H | h | -header
.Op Fl P | -plugins
.Op Fl R | -remote
.Op Fl b | r | -base | -release | Cm dataset_type
.Op Fl l | -long
.Op Fl q | -quick
.Op Fl s | -sort
.Op Fl t | -template | Cm dataset_type
.Op Fl PRO
.\" == MIGRATE ==
.Nm
.Cm migrate
.Op Fl d | -delete
.Op Fl f | -force
.\" == PKG ==
.Nm
.Cm pkg
.Ar UUID | NAME
.Ar COMMAND
.\"== RENAME ==
.Nm
.Cm rename
.Ar UUID | NAME
.Ar NEW_NAME
.\" == RESTART ==
.Nm
.Cm restart
.Op Fl s | -soft
.Ar UUID | NAME
.\" == ROLLBACK ==
.Nm
.Cm rollback
.Op Fl f | -force
.Fl n | -name Ar TEXT
.Ar UUID | NAME
.\" == SET ==
.Nm
.Cm set
.Ar PROPERTY Op ...
.Ar UUID | NAME
.Op Fl P | -plugin Ar KEY
.\" == SNAPLIST ==
.Nm
.Cm snaplist
.Ar UUID | NAME
.Op Fl H | h | -header
.Op Fl l | -long
.Op Fl s | -sort Cm TYPE
.\" == SNAPREMOVE ==
.Nm
.Cm snapremove
.Op Fl n | -name Ar TEXT
.Ar UUID | NAME | ALL
.\" == SNAPSHOT ==
.Nm
.Cm snapshot
.Op Fl n | -name Ar TEXT
.Ar UUID | NAME
.\" == START ==
.Nm
.Cm start
.Op Fl -rc
.Op Ar UUID | NAME | ALL
.\" == STOP ==
.Nm
.Cm stop
.Op Fl -rc
.Op Ar UUID | NAME | ALL
.\" == UPDATE ==
.Nm
.Cm update
.Ar UUID | NAME
.\" == UPGRADE ==
.Nm
.Cm upgrade
.Ar UUID | NAME
.Fl r | -release Ar RELEASE
.Sh DESCRIPTION
.Nm
is a system administration tool designed to simplify jail management
tasks.
It abstracts out the management of ZFS-backed jails running VNET or
shared IP networking.
.Pp
Both shared IP jails and VNET jails are supported.
.Pp
Each jail has a unique ID (UUID) which is automatically generated at
creation time.
Using the UUID as a jail identifier is more flexible when replicating
a jail in a distributed environment.
This also eliminates potential naming clashes on large scale
deployments and helps reduce operator error.
.Pp
Partial UUID calling is supported with every operation.
For example,
.Ar adae47cb-01a8-11e4-aa78-3c970ea3222f
can be used in the form of
.Ar adae47cb
or just
.Ar adae .
In addition to partial UUID calling, jail NAMEs can also be used.
.Pp
Jails can be easily moved with ZFS
.Cm send
and
.Cm receive ,
preserving all of their properties automatically.
.Pp
.Nm
relies on ZFS and at least one ZFS pool must be present on the host
system.
Bridge interfaces like
.Pa bridge0
or
.Pa bridge1
are required for VNET and can be enabled by adding this line to
.Pa /etc/rc.conf :
.Bd -literal -offset indent
cloned_interfaces="bridge0 bridge1"
.Ed
.Pp
To enable all the features
.Nm
supports, consider building a kernel with these options:
.Bd -literal -offset indent
options VIMAGE
options RACCT
options RCTL
.Ed
.Sh SUBCOMMANDS
.Bl -tag -width ".Cm activate"
.\" == Debug ==
.It Fl D | -debug
Log
.Nm
debug output to the console.
.\" == Help ==
.It Fl -help
Display
.Nm
help text.
Including
.Fl -help
after a specific subcommand displays help text for that command.
.\" == VERSION ==
.It Fl -version
Display the
.Nm
version number.
.\" == ACTIVATE ==
.It Cm activate
Intended for use by automation tools.
The pool can be activated for
.Nm
jails without requiring user input.
By default, all other pools are deactivated.
.Pp
Example:
.Pp
.Dl # iocage activate examplezpool
.Pp
.\" == CHROOT ==
.It Cm chroot
Chroot into a jail without actually starting the jail itself.
Useful for initial setup like setting a root password or configuring
networking.
A command can be specified as with the normal system, see
.Xr chroot 8 .
.Pp
Example:
.Pp
.Dl # iocage chroot 6ffe99a9 ls
.Pp
Run
.Cm ls
in the jail identified by the shortened UUID.
.\" == CLEAN ==
.It Cm clean
Destroy ZFS datasets.
.Pp
Options:
.Bl -tag -width "[-b | --base | -r | dataset_type]"
.It Op Fl a | -all | Cm dataset_type
Destroys all created iocage data.
.It Op Fl b | r | -base | Cm dataset_type
Destroys all fetched RELEASE jails.
.It Op Fl f | -force
Runs the command without any further user interaction.
.It Op Fl j | -jails | Cm dataset_type
Destroys all created jails.
.It Op Fl t | -template | Cm dataset_type
Destroys all templates.
.El
.Pp
Example:
.Pp
.Dl # iocage clean -j
.Pp
Destroys all created jails on the system, after a prompt ensures this
is the desired action.
.Pp
.\"== CLONE ==
.It Cm clone
Clone a jail.
Properties can be configured for the clone by listing them after the
.Ar UUID | NAME .
.Pp
Options:
.Bl -tag -width "[-c | --count TEXT]"
.It Op Fl c | -count Ar TEXT
Designate the number of jails to create, all cloned from
the desired jail.
.El
.Pp
Examples:
.Pp
.Dl # iocage clone 38114a58 --name cloneexample1
.Pp
Clone jail 38114a58 and add the name cloneexample1 to the new jail.
.Pp
.Dl # iocage clone exampjail -c 3
Creates three jail clones of exampjail.
.Pp
.\" == CONSOLE ==
.It Cm console
Execute login to open a shell inside the jail.
.Pp
Options:
.Bl -tag -width "[-f | --force TEXT]"
.It Op Fl f | -force
Start the jail if it is not running.
.El
.Pp
Examples:
.Pp
.Dl # iocage console cloneexample1
.Pp
.Dl # iocage console -f jail1
.Pp
.\" == CREATE ==
.It Cm create
Deploy a new jail based on the host operating system's RELEASE.
The default can be overridden by specifying the RELEASE option.
A fully independent jail set is created by default.
.Pp
Options:
.Bl -tag -width "[-B | --clone_basejail]"
.It Op Fl b | -basejail
Create a new "basejail".
Basejails copy the RELEASE and mount the designated RELEASE
directories as nullfs mounts over the jail directories.
.It Op Fl c | -count Ar TEXT
Designate the number of jails to create, all cloned from
the desired
.Op Fl r Ar RELEASE .
.It Op Fl e | -empty
Create an empty jail for unsupported or custom jails.
.It Op Fl f | -force
Skip prompts, auto-confirming them with yes.
.It Op Fl n | -name Ar TEXT
Provide a NAME instead of a UUID for the new jail.
.It Op Fl p | -pkglist Ar TEXT
Specify a JSON file which manages the installation of each
package in the newly created jail.
.It Op Fl r | -release Ar TEXT
Specify which RELEASE to use for the new jail.
.It Op Fl r | -release Cm latest | Cm LATEST
Creat a new jail with the latest release available.
.It Op Fl s | -short
Use a short UUID of 8 characters instead of the default 36.
.It Op Fl t | -template Ar TEXT
Create a jail from the specified template.
.It Op Fl B | -clone_basejail
Create a new "clone basejail".
Clone basejails clone the RELEASE with ZFS and mount the designated
RELEASE directories as nullfs mounts over the jail directories.
.It Op Fl T | -thickjail
Thick jails are copies of the release, not clones.
.It Op Fl u | -uuid Ar TEXT
Specify a desired UUID for the new jail.
.El
.Pp
Examples:
.Pp
.Dl # iocage create -s -r 11.0-RELEASE
.Pp
Create a FreeBSD 11.0 jail with a shortened UUID.
.Pp
.Dl # iocage create -r 11.0-RELEASE -u 12345678
.Pp
Create a FreeBSD 11.0 jail with the custom UUID 12345678.
.Pp
.Dl # iocage create -c 3 -r 11.0-RELEASE -n examplejail
.Pp
This command creates three identical jails based off the
FreeBSD 11.0 RELEASE.
These jails are sequentially numbered based on the
custom NAME.
.\" == DESTROY ==
.It Cm destroy
Destroy the specified jail.
Caution, this subcommand is irreversible.
.Cm destroy
only works with a stopped jail.
.Pp
Options:
.Bl -tag -width "[-d | --download]"
.It Op Fl R | -recursive
Skip the destroy children prompt.
This is best used with the
.Op Fl f | -force
option.
.It Op Fl d | -download
Also destroy the specified RELEASE download.
.It Op Fl f | -force
Destroy the jail with no further warnings or user input.
.It Op Fl r | -release
Destroy a specified RELEASE dataset.
.El
.Pp
Examples:
.Pp
.Dl # iocage destroy 12345678 -f
.Pp
Destroy the identified jail with no further input.
.Pp
.Dl # iocage destroy -r 10.1-RELEASE
.Pp
Destroy the downloaded FreeBSD 10.1 release.
.Pp
.\" == DF ==
.It Cm df
Show resource usage of all jails.
Invoking
.Cm df
displays a table with several fields:
.Pp
.Bl -tag -width "UUID" -compact -offset indent
.It UUID
unique jail ID
.It CRT
compression ratio
.It RES
reserved space
.It QTA
disk quota
.It USE
used space
.It AVA
available space
.It NAME
jail name
.El
.Pp
Options:
.Bl -tag -width "[-H | -h | --header]"
.It Op Fl H | h | -header
Use when scripting, using tabs for separators.
.It Op Fl l | -long
Shows the full UUID.
.It Op Fl s | -sort Ar TEXT
Sorts the list by the named type.
.El
.Pp
Example:
.Pp
.Dl # iocage df -l
.Pp
Displays the usage table with the full UUID of each jail.
.Pp
.\" == EXEC ==
.It Cm exec
Execute a command inside the specified jail.
This is an
.Nm
UUID/NAME wrapper for
.Xr jexec 8 .
After invoking
.Cm exec ,
specify the jail, any commands to run inside that jail, and any
arguments for those commands.
.Xr jexec
also runs commands similar to
.Nm .
When using
.Xr jexec
use the JID instead of the jail name.
For more info see the manual page for
.Xr jexec .
Use -- in front of the specified command to prevent iocage from parsing
them.
.Pp
Options:
.Bl -tag -width "[-u | --host_user NAME]"
.It Op Fl f | -force
Start the jail if it is not running.
.It Op Fl U | -jail_user Ar NAME
Specifies which jail user runs the command.
.It Op Fl u | -host_user Ar NAME
Specify which host user runs the command.
.El
.Pp
Examples:
.Pp
.Dl # iocage exec -f examplejail_1 ls /tmp
.Pp
Starts examplejail_1 and lists the contents of the
.Pa /tmp
directory.
.Pp
.Dl # iocage exec examplejail_1 "cat COPYRIGHT" | less
.Pp
In this example, examplejail_1 executes
.Cm cat COPYRIGHT ,
while the output is run with
.Cm less
outside the jail on the primary system.
.Pp
.\" == EXPORT ==
.It Cm export
Exports the specified jail.
An archive file is created in
.Pa /iocage/images
with an SHA256 checksum.
The jail must be stopped before exporting.
.Pp
Example:
.Pp
.Dl # iocage export examplejail_2
.Pp
.\" == FETCH ==
.It Cm fetch
Downloads and/or updates releases.
.Pp
.Cm fetch
must be executed as the first command on a pristine system.
The host node's RELEASE is downloaded for deployment.
If other releases are required, this can be changed by supplying the
required release property or selecting the appropriate RELEASE from
the menu list.
.Pp
Options:
.Bl -tag -width "[-plugins -official OPTIONS]"
.It Op Fl -accept
Accept the plugin's LICENSE agreement.
.It Op Fl -noaccept
Do not accept the plugin's LICENSE agreement.
.It Op Fl -plugins Ar OPTIONS
Fetch and create a plugin.
.It Op Fl -plugins Fl -official Ar OPTIONS
Fetch and create an official FreeNAS plugin.
.It Op Fl E | -eol
Enable End Of Life (EOL) checking upstream.
.It Op Fl F | -files Ar TEXT
Uses a local file directory for the root directory instead of HTTP.
.It Op Fl NE | -noeol
Disable EOL checking upstream.
.It Op Fl NU | -noupdate
Disable updating the fetch item to the latest patch level.
.It Op Fl NV | -noverify
Disable verifying the SSL cert for HTTP fetching.
.It Op Fl P | -plugin-file Ar TEXT
Specify which plugin file to use.
.It Op Fl U | -update
Update the fetch to the latest patch level.
.It Op Fl V | -verify
Enable verifying the SSL cert for HTTP fetching.
.It Op Fl a | -auth Ar TEXT
Specifies the authentication method for HTTP fetching.
Current values are basic and digest.
.It Op Fl c | -count Ar TEXT
Used when fetching a plugin.
This option creates the designated number of plugin type jails.
.It Op Fl d | -root-dir Ar TEXT
Specify the root directory containing all RELEASE files.
.It Op Fl f | -file
Use a local file directory for the root directory instead of HTTP.
.It Op Fl h | -http
No-op flag for backwords compatibility.
Previous versions of
.Nm
used this to adjust
.Op Fl s | -server
to define an HTTP server.
.It Op Fl p | -password Ar TEXT
Add a password, if required.
.It Op Fl r | -release Ar TEXT
Define the
.Fx
release to fetch.
.It Op Fl r Cm latest | Cm LATEST
Fetches the latest release.
.It Op Fl s | -server Ar TEXT
Define the server from which to fetch the RELEASE.
.It Op Fl u | -user Ar TEXT
Define the user.
.El
.Pp
Examples:
.Pp
.Dl # iocage fetch
.Pp
.Nm
lists available FreeBSD releases and asks which to download.
Enter the numeric option for the desired release, or type EXIT
to quit without downloading.
.Pp
.Dl # iocage fetch --release 10.3-RELEASE
.Pp
This tells
.Nm
to download and automatically update the FreeBSD 10.3 RELEASE.
This can also be used to apply the latest patches to an already
downloaded release.
Newly created jails or basejails are automatically updated.
.Pp
.Dl # iocage fetch -NE -r 11.0-RELEASE
.Pp
This disables the end of life check, then fetches the FreeBSD 11.0
release and updates with the latest patches.
.Pp
.Dl # iocage fetch -r LATEST
.Pp
This fetches the latest release available.
.\" == FSTAB ==
.It Cm fstab
Manipulates the fstab settings of a specific jail.
Name any options, then the jail, and finally all needed fstab strings.
.Pp
Options:
.Bl -tag -width "[-r | --remove | action]"
.It Op Fl H | h | -header
For scripting.
Use tabs for separators.
.It Op Fl R | -replace
Replace an entry by index number.
.It Op Fl a | -add | Cm action
Adds an entry to the specific jail's
.Pa fstab
and mounts it.
.It Op Fl e | -edit | Cm action
Opens the
.Pa fstab
file in the default editor.
.It Op Fl l | -list
List the jail's fstab.
.It Op Fl r | -remove | Cm action
Remove an entry from a specific jail's
.Pa fstab
and unmounts it.
.El
.Pp
Example:
.Pp
.Dl # iocage fstab -a example_jail_1 /usr/home /usr/home nullfs rw 0 0
.Pp
.\" == GET ==
.It Cm get
Display the specified property.
List the property, then the UUID or NAME of the jail to search.
.Pp
Options:
.Bl -tag -width "[-H | -h | --header]"
.It Op Fl H | h | -header
Used in scripting.
Use tabs for separators.
.It Op Fl P | -plugin Op Fl f | -force
Get the specified key for a plugin jail.
The
.Fl f | -force
option starts the jail if it is not already running.
.Fl f | -force
only works with
.Fl P | -plugin .
.It Op Fl a | -all
Get all properties for the specified jail.
If accessing a nested key, use "." as a separator.
.It Op Fl p | -pool
Get the currently activated zpool.
.It Op Fl r | -recursive
Get the specified property for all jails.
.It Op Fl s | Cm state
Return the state of the jail.
.It Op Fl j | Cm JID
Return the JID.
.El
.Pp
Examples:
.Pp
.Dl # iocage get -p
.Pp
Outputs the name of the activated zpool.
.Pp
.Dl # iocage get -a examplejail_1 | less
.Pp
List all properties of examplejail_1 and send the output
through
.Cm less .
.Pp
.Dl # iocage get -r dhcp
.Pp
Displays a table with each jail's UUID or NAME and the
status of the requested property.
.Pp
.Dl # iocage get -s examplejail_1
.Pp
Return whether the state of the jail is up or down.
.Pp
.\" == IMPORT ==
.It Cm import
Import a specific jail image.
Short UUIDs can be used, but do not specify the full filename, only
the UUID.
.Pp
Example:
.Pp
.Dl # iocage import 064c247
.Pp
.\" == LIST ==
.It Cm list
List the specified dataset type.
By default, all jails are listed.
.Pp
Options:
.Bl -tag -width "[-H | -h | --header]"
.It Op Fl -http
Changes
.Op Fl R | -remote
to use HTTP.
.It Op Fl H | h | -header
Used in scripting.
Use tabs for separators.
.It Op Fl P | -plugins
Shows plugins installed on the system.
.It Op Fl PRO
Lists official plugins available for download.
.It Op Fl R | -remote
Shows available RELEASE options for remote.
.It Op Fl b | r | -base | -release | Cm dataset_type
List all bases.
.It Op Fl l | -long
Shows JID, NAME, BOOT, STATE, TYPE, RELEASE, IP4, IP6, and
TEMPLATE information.
.It Op Fl q | -quick
Lists all jails with less processing and fields.
.It Op Fl s | -sort Ar TEXT
Sorts the list by the given type.
.It Op Fl t | -template | Cm dataset_type
Lists all templates.
.El
.Pp
Example:
.Pp
.Dl # iocage list
.Pp
Displays a table containing several elements for
each installed jail:
.Bl -tag -width "release"
.It JID
Jail identifier
.It UUID
Unique identifcation number.
.It STATE
Displays the active state of the jail.
Can be up or down.
.It NAME
The user assigned NAME.
.It RELEASE
The jail's FreeBSD RELEASE.
.It IP4
Shows the availability of IP4 addresses.
.El
.Pp
.\" == MIGRATE ==
.It Cm migrate
Migrate from the development version of iocage-legacy to the current
jail format.
.Pp
Options:
.Bl -tag -width "[-d | --delete]"
.It Op Fl d | -delete
Destroy the old dataset after migration.
.It Op Fl f | -force
Bypass any further warning or required user interaction.
.El
.Pp
Example:
.Pp
.Dl # iocage migrate -d -f
.Pp
Migrates to the new jail format and deletes the old dataset with
no further user interaction.
.Pp
.\" == PKG ==
.It Cm pkg
Run desired
.Cm pkg
commands in the specified jail.
List the jail's UUID or NAME, then any desired commands.
.Pp
.\" == RENAME ==
.It Cm rename
Rename the specified jail.
.Pp
Examples:
.Pp
.Dl # iocage rename jail1 NEWNAME
.Dl Jail: jail1 renamed to NEWNAME
.Pp
.\" == RESTART ==
.It Cm restart
Restart the specified jail, OR use ALL to restart all jails.
.Pp
Options:
.Bl -tag -width "[-s | --soft]"
.It Op Fl s | -soft
Restart the jail, but do not tear down the network stack.
.El
.Pp
Examples:
.Pp
.Dl # iocage restart ALL
.Pp
.Dl # iocage restart --soft examplejail1
.Pp
.\" == ROLLBACK ==
.It Cm rollback
Roll back a jail to an existing snapshot.
Any intermediate snapshots are destroyed in the process.
For more information on this functionality, please see
.Xr zfs 8 .
.Pp
Options:
.Bl -tag -width "[-f | --force]"
.It Op Fl f | -force
Run the command, skipping any warnings or further user interaction.
.It Fl n | -name Ar TEXT
[Required] Used to specify the snapshot name.
.El
.Pp
Example:
.Pp
.Dl # iocage rollback -n snapshottest2 examplejail1
.Pp
.\" == SET ==
.It Cm set
Set the specified properties in the desired jail.
Type the desired properties separated by a space, then the jail
UUID or NAME to apply the changes.
.Pp
Options:
.Bl -tag -width "[-P | --plugin]"
.It Op Fl P | -plugin Ar KEY
Set the specified key for a plugin jail.
If accessing a nested key, use "." as a separator.
.El
.Pp
Examples:
.Pp
.Dl # iocage set boot=1 notes="Example note." testjail -P foo.bar.baz=VALUE PLUGIN
.Pp
.\" == SNAPLIST ==
.It Cm snaplist
List snapshots of a jail.
A number of different fields are displayed:
.Pp
.Bl -tag -width "CREATED" -compact -offset indent
.It NAME
snapshot name
.It CREATED
creation time
.It RSIZE
referenced size
.It USED
used space
.El
.Pp
Options:
.Bl -tag -width "[-H | -h | --delete]"
.It Op Fl H | h | -header
Used for scripting.
Tabs are used as separators.
.It Op Fl l | -long
Show the full dataset path for the snapshot.
.It Op Fl s | -sort Cm TYPE
Sort the returned list by the named TYPE.
.El
.Pp
Example:
.Pp
.Dl # iocage snaplist examplejail1
.Pp
.Dl # iocage snaplist FOO -s name
.Pp
.\" == SNAPREMOVE ==
.It Cm snapremove
Delete snapshots of the specified jail.
If the keyword
.Op Ar ALL
is used, all snapshots the specified jail are deleted.
.Pp
Options:
.Bl -tag -width "[-n | --name]"
.It Op Fl n | -name Ar TEXT
[Required] The snapshot name.
.El
.Pp
Example:
.Pp
.Dl # iocage snapremove -n snapshottest1 examplejail1
.Pp
.\" == SNAPSHOT ==
.It Cm snapshot
Create a ZFS snapshot of the specified jail.
If a snapshot name is not specified, a name based on the current
date and time is generated.
.Pp
Options:
.Bl -tag -width "[-n | --name TEXT]"
.It Op Fl n | -name Ar TEXT
The user created snapshot name.
.El
.Pp
Example:
.Pp
.Dl # iocage snapshot examplejail1 -n snapshottest1
.Pp
.\" == START ==
.It Cm start
Start a jail identified by
.Ar UUID
or
.Ar NAME .
Use
.Op Ar ALL
to start all installed jails instead.
.Pp
Options:
.Bl -tag -width "[--rc]"
.It Op Fl -rc
Start all jails with boot=1 in a specific order.
Jails with lower priority start first.
.El
.Pp
Example:
.Pp
.Dl # iocage start examplejail1
.Pp
.\" == STOP ==
.It Cm stop
Stop a jail identified by
.Ar UUID
or
.Ar NAME .
Use
.Op Ar ALL
to stop all active jails instead.