1nbdkit-S3-plugin(1)                 NBDKIT                 nbdkit-S3-plugin(1)
2
3
4

NAME

6       nbdkit-S3-plugin - open disk images stored in Amazon S3 or Ceph
7

SYNOPSIS

9        nbdkit S3 [access-key=...] [secret-key=...] [session-token=...]
10                  [endpoint-url=...]
11                  bucket=BUCKET key=FILENAME
12

DESCRIPTION

14       "nbdkit-S3-plugin" is a plugin for nbdkit(1) which lets you open single
15       files stored in Amazon S3 or Ceph as disk images.
16
17       Currently it only allows read access, although write access may be
18       added in future.
19
20       This plugin uses the Python Amazon Web Services SDK called Boto3.
21

EXAMPLE

23        nbdkit S3 endpoint-url=https://ceph.example.com \
24                  bucket=MY-BUCKET key=disk.img
25

PARAMETERS

27       access-key=ACCESS_KEY
28       secret-key=SECRET_KEY
29       session-token=SESSION_TOKEN
30           The AWS credentials may be specified on the command line using
31           these parameters, but it is more secure to pass them using files
32           (see "CREDENTIALS" below).
33
34       endpoint-url=ENDPOINT
35           If accessing Ceph or another compatible S3 service, provide the
36           endpoint URL through this parameter.
37
38       bucket=BUCKET
39           The bucket containing the file.  This parameter is required.
40
41       key=FILENAME
42           The file name within the bucket.  This parameter is required.
43

CREDENTIALS

45       Although AWS credentials can be passed to nbdkit on the command line,
46       this is not secure since a user on the same machine could read them
47       using ps(1).
48
49       A better way is to pass the credentials through the ~/.aws/credentials
50       file.  This takes the form:
51
52        [default]
53        aws_access_key_id = XXX
54        aws_secret_access_key = YYY
55
56        [profile]
57        aws_access_key_id = XXX
58        aws_secret_access_key = YYY
59
60       Different profiles from the file can be selected by setting the
61       "AWS_PROFILE" environment variable.
62
63       There is much more information about credentials in the Boto3
64       documentation.
65

COMPARED TO S3FS-FUSE

67       s3fs-fuse (https://github.com/s3fs-fuse/s3fs-fuse) presents a whole S3
68       bucket as a FUSE filesystem, with each object in the bucket
69       corresponding to a single file.  It is therefore quite different from
70       this plugin which turns a single S3 object into a block device.
71

FILES

73       $plugindir/nbdkit-S3-plugin
74           The plugin.
75
76           Use "nbdkit --dump-config" to find the location of $plugindir.
77
78       $HOME/.aws/credentials
79           AWS credentials can be passed to boto3 using this file.
80

ENVIRONMENT VARIABLES

82       "AWS_*"
83           Boto3 reads some credential information from "AWS_*" environment
84           variables.
85

VERSION

87       "nbdkit-S3-plugin" first appeared in nbdkit 1.24.
88

SEE ALSO

90       nbdkit(1), nbdkit-plugin(3), nbdkit-python-plugin(3),
91       https://pypi.org/project/boto3/,
92       https://boto3.amazonaws.com/v1/documentation/api/latest/index.html,
93       https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html.
94

AUTHORS

96       Richard W.M. Jones
97

99       Copyright (C) 2020 Red Hat Inc.
100

LICENSE

102       Redistribution and use in source and binary forms, with or without
103       modification, are permitted provided that the following conditions are
104       met:
105
106       •   Redistributions of source code must retain the above copyright
107           notice, this list of conditions and the following disclaimer.
108
109       •   Redistributions in binary form must reproduce the above copyright
110           notice, this list of conditions and the following disclaimer in the
111           documentation and/or other materials provided with the
112           distribution.
113
114       •   Neither the name of Red Hat nor the names of its contributors may
115           be used to endorse or promote products derived from this software
116           without specific prior written permission.
117
118       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
119       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
120       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
121       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
122       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
123       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
124       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
125       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
126       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
127       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
128       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
129
130
131
132nbdkit-1.28.2                     2021-11-09               nbdkit-S3-plugin(1)
Impressum