plugins/S3/nbdkit-S3-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-S3-plugin - expose data in Amazon S3 or Ceph buckets as block device
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit S3 [access-key=...] [secret-key=...] [session-token=...]
   8            [endpoint-url=...]
   9            [size=NN object-size=NN]
  10            bucket=BUCKET key=STRING
  11
  12 =head1 DESCRIPTION
  13
  14 C<nbdkit-S3-plugin> is a plugin for L<nbdkit(1)> which lets you open
  15 objects stored in Amazon S3 or Ceph as disk images.
  16
  17 This plugin uses the Python Amazon Web Services SDK called Boto3.
  18
  19 =head1 EXAMPLES
  20
  21  nbdkit S3 endpoint-url=https://ceph.example.com \
  22            bucket=MY-BUCKET key=disk.img
  23
  24
  25 Provides read only block device holding the data contained in the "disk.img"
  26 object.
  27
  28  nbdkit S3 endpoint-url=https://ceph.example.com \
  29            size=50G object-size=128k \
  30            bucket=MY-BUCKET key=disk
  31
  32 Provides a read-write block device with size 50G, whose contents are stored
  33 multiple in objects of size 128k, prefixed with I<disk/>
  34
  35 =head1 PARAMETERS
  36
  37 =over 4
  38
  39 =item B<access-key=>ACCESS_KEY
  40
  41 =item B<secret-key=>SECRET_KEY
  42
  43 =item B<session-token=>SESSION_TOKEN
  44
  45 The AWS credentials may be specified on the command line using these
  46 parameters, but it is more secure to pass them using files (see
  47 L</CREDENTIALS> below).
  48
  49 =item B<endpoint-url=>ENDPOINT
  50
  51 If accessing Ceph or another compatible S3 service, provide the
  52 endpoint URL through this parameter.
  53
  54 =item B<bucket=>BUCKET
  55
  56 The bucket containing the object(s).  This parameter is required.
  57
  58 =item B<key=>STRING
  59
  60 The object name (if C<size> is not specified) or object prefix (if
  61 C<size> is specified) to use within the bucket.  This parameter is
  62 required.
  63
  64 =item B<size=>SIZE
  65
  66 =item B<object-size=>SIZE
  67
  68 These two parameters must always be specified together. If set, data
  69 will be split into blocks of C<object-size> and stored as separate
  70 objects. The block device will report a total size of C<size> and be
  71 writeable and trim-able.
  72
  73 Object names will have the form I<key/%16x>, where C<%16x> is the
  74 16-digit hexadecimal block number. If there are existing objects
  75 under such name that do not have the expected size, the plugin
  76 will crash.
  77
  78 =back
  79
  80 =head1 PERFORMANCE CONSIDERATIONS
  81
  82 It is highly recommended that clients do their utmost to issue
  83 requests that exactly match the object size: Smaller write requests
  84 will incur a performance penalty due to the need for read-modify-write
  85 cycles (thus also incurring latency from two network
  86 round-trips). Larger read and write requests will incur a performance
  87 penalty because of sequential execution.
  88
  89 The L<nbdkit-blocksize-filter(1)> can be used to alleviate the impact
  90 of requests larger than the object size, but does not help if the
  91 client issues requests smaller than the block size.
  92
  93 The L<nbdkit-stats-filter(1)> can be used to investigate what block
  94 sizes and alignments are used by the client.
  95
  96 When connecting through the Linux kernel's NBD module, consider
  97 setting C</sys/block/nbdE<lt>XE<gt>/queue/max_sectors_kb> to match the
  98 object size.
  99
 100 =head1 CREDENTIALS
 101
 102 Although AWS credentials can be passed to nbdkit on the command line,
 103 this is not secure since a user on the same machine could read them
 104 using L<ps(1)>.
 105
 106 A better way is to pass the credentials through the
 107 F<~/.aws/credentials> file.  This takes the form:
 108
 109  [default]
 110  aws_access_key_id = XXX
 111  aws_secret_access_key = YYY
 112
 113  [profile]
 114  aws_access_key_id = XXX
 115  aws_secret_access_key = YYY
 116
 117 Different profiles from the file can be selected by setting
 118 the C<AWS_PROFILE> environment variable.
 119
 120 There is much more information about credentials in
 121 L<the Boto3 documentation|https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html>.
 122
 123 =head1 COMPARISON TO S3FS-FUSE AND S3BACKER
 124
 125 s3fs-fuse (L<https://github.com/s3fs-fuse/s3fs-fuse>) and s3backer
 126 (L<https://github.com/archiecobbs/s3backer>) provide similar
 127 functionality but are based on FUSE (rather than NBD). They provide a
 128 regular file (backed by S3) which can then be loopback-mounted to
 129 provide a block device. s3backer also supports to optionally encrypt
 130 and compress objects.
 131
 132 In theory, NBD should provide better performance than FUSE, because:
 133
 134 =over 4
 135
 136 =item * The kernel no longer serializes write and read requests but
 137 issues them concurrently.
 138
 139 =item * Read and write request size can exceed 128 kB
 140
 141 =item * The system can still be reliably hibernated (a running FUSE
 142 daemon may prevent this)
 143
 144 =item * Requests pass through the VFS only once, not twice
 145
 146 =item * Data is present in the page cache only once, not twice
 147
 148 =back
 149
 150 However, for high-bandwith network connections s3backer and s3fs-fuse
 151 may be faster because they are written in C rather than Python.
 152
 153 =head1 FILES
 154
 155 =over 4
 156
 157 =item F<$plugindir/nbdkit-S3-plugin>
 158
 159 The plugin.
 160
 161 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 162
 163 =item F<$HOME/.aws/credentials>
 164
 165 AWS credentials can be passed to boto3 using this file.
 166
 167 =back
 168
 169 =head1 ENVIRONMENT VARIABLES
 170
 171 =over 4
 172
 173 =item C<AWS_*>
 174
 175 Boto3 reads some credential information from C<AWS_*> environment variables.
 176
 177 =back
 178
 179 =head1 VERSION
 180
 181 C<nbdkit-S3-plugin> first appeared in nbdkit 1.24.
 182
 183 =head1 SEE ALSO
 184
 185 L<nbdkit(1)>,
 186 L<nbdkit-plugin(3)>,
 187 L<nbdkit-python-plugin(3)>,
 188 L<https://pypi.org/project/boto3/>,
 189 L<https://boto3.amazonaws.com/v1/documentation/api/latest/index.html>,
 190 L<https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html>.
 191
 192 =head1 AUTHORS
 193
 194 Richard W.M. Jones
 195
 196 Nikolaus Rath
 197
 198 =head1 COPYRIGHT
 199
 200 Copyright Red Hat