plugins/iso/nbdkit-iso-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-iso-plugin - create virtual ISO (CD-ROM) from directory
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit iso [dir=]DIRECTORY [[dir=]DIRECTORY ...]
   8             [prog=mkisofs] [params='-JrT']
   9
  10 =for paragraph
  11
  12  nbdkit iso --dump-plugin
  13
  14 =head1 DESCRIPTION
  15
  16 C<nbdkit-iso-plugin> is a plugin for L<nbdkit(1)> which creates a
  17 virtual ISO (CD-ROM) image from a directory on the fly.  The files
  18 from F<DIRECTORY> are added to a virtual ISO image which is served
  19 read-only over the NBD protocol.
  20
  21 This plugin uses L<xorriso(1)>, L<genisoimage(1)> or L<mkisofs(1)> to
  22 create the ISO content.  See also L</DUMP PLUGIN OUTPUT> below.
  23
  24 To create a FAT-formatted virtual floppy disk instead of a CD, see
  25 L<nbdkit-floppy-plugin(1)>.  To create a Linux compatible virtual
  26 disk, see L<nbdkit-linuxdisk-plugin(1)>.
  27
  28 =head1 EXAMPLE
  29
  30 Create a virtual ISO which supports Joliet, Rock Ridge and TRANS.TBL
  31 extensions, from files in a directory:
  32
  33  nbdkit iso /path/to/directory params='-JrT'
  34
  35 C<params> adds I<-JrT> to the L<xorriso(1)>, L<genisoimage(1)> or
  36 L<mkisofs(1)> command line, specifying the required extensions.  Note
  37 that unless you use at least one of these extensions, filenames inside
  38 the ISO will be truncated because of limitations of the basic S<ISO
  39 9660> format.
  40
  41 =head1 PARAMETERS
  42
  43 =over 4
  44
  45 =item [B<dir=>]DIRECTORY
  46
  47 Specify the directory containing files and subdirectories which will
  48 be added to the virtual ISO.  Files inside this directory will appear
  49 in the root directory of the ISO.
  50
  51 This parameter is required and may be specified one or more times.  If
  52 multiple directories are specified, they are merged together.
  53
  54 C<dir=> is a magic config key and may be omitted in most cases.
  55 See L<nbdkit(1)/Magic parameters>.
  56
  57 =item B<params=>'parameters ...'
  58
  59 Any other parameters may be passed through to L<xorriso(1)>,
  60 L<genisoimage(1)> or L<mkisofs(1)> by specifying this option.
  61
  62 For example:
  63
  64  params='-JrT -V "My Disk Image"'
  65
  66 would specify Joliet (I<-J>), Rock Ridge (I<-r>) and TRANS.TBL (I<-T>)
  67 extensions, and specify the volume ID (I<-V>) as C<My Disk Image>.
  68
  69 Take care when quoting this parameter; nbdkit passes the resulting
  70 string through another layer of shell interpretation without any
  71 sanity checks for unquoted shell metacharacters.
  72
  73 =item B<prog=>mkisofs
  74
  75 Choose which program to use to create the ISO content.  The default is
  76 L<xorriso(1)>, L<genisoimage(1)> or L<mkisofs(1)> and is picked when
  77 nbdkit is compiled.  You only need to use this parameter if you want
  78 to override it at run time.
  79
  80 =back
  81
  82 =head1 DUMP PLUGIN OUTPUT
  83
  84 Use:
  85
  86  nbdkit iso --dump-plugin
  87
  88 to find out which mkisofs-like program was used when the plugin was
  89 compiled.  For example:
  90
  91  $ nbdkit iso --dump-plugin | grep ^iso_prog=
  92  iso_prog=xorriso
  93
  94 =head1 ENVIRONMENT VARIABLES
  95
  96 =over 4
  97
  98 =item C<PATH>
  99
 100 L<xorriso(1)>, L<genisoimage(1)>, L<mkisofs(1)> or whatever you supply
 101 to the optional C<prog> parameter must be available on the C<$PATH>.
 102
 103 =item C<TMPDIR>
 104
 105 A temporary copy of the ISO is created in C<TMPDIR>.  If this
 106 environment variable is not set then F</var/tmp> is used instead.
 107 There must be enough free space here to store the ISO, which might be
 108 quite large.
 109
 110 =back
 111
 112 =head1 FILES
 113
 114 =over 4
 115
 116 =item F<$plugindir/nbdkit-iso-plugin.so>
 117
 118 The plugin.
 119
 120 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 121
 122 =back
 123
 124 =head1 VERSION
 125
 126 C<nbdkit-iso-plugin> first appeared in nbdkit 1.8.
 127
 128 =head1 SEE ALSO
 129
 130 L<nbdkit(1)>,
 131 L<nbdkit-plugin(3)>,
 132 L<nbdkit-file-plugin(1)>,
 133 L<nbdkit-floppy-plugin(1)>,
 134 L<nbdkit-linuxdisk-plugin(1)>,
 135 L<nbdkit-torrent-plugin(1)>,
 136 L<genisoimage(1)>,
 137 L<mkisofs(1)>,
 138 L<xorriso(1)>.
 139
 140 =head1 AUTHORS
 141
 142 Richard W.M. Jones
 143
 144 =head1 COPYRIGHT
 145
 146 Copyright (C) 2018 Red Hat Inc.