Upload-file command

Uploads one file to the given bucket.

Uploads the contents of the local file, and assigns the given name to the B2 file, possibly setting options like server-side encryption and retention.

A FIFO file (such as named pipe) can be given instead of regular file.

By default, upload_file will compute the sha1 checksum of the file to be uploaded. But, if you already have it, you can provide it on the command line to save a little time.

Warning

Setting file retention mode to ‘compliance’ is irreversible - such files can only be ever deleted after their retention period passes, regardless of keys (master or not) used. This is especially dangerous when setting bucket default retention, as it may lead to high storage costs.

Content type is optional. If not set, it will be guessed.

The maximum number of upload threads to use to upload parts of a large file is specified by --threads. It has no effect on “small” files (under 200MB as of writing this).

Each fileInfo is of the form a=b.

By default, the file is broken into many parts to maximize upload parallelism and increase speed. Setting --min-part-size controls the minimal upload file part size. Part size must be in 5MB to 5GB range. Reference: https://www.backblaze.com/docs/cloud-storage-create-large-files-with-the-native-api

If the tqdm library is installed, progress bar is displayed on stderr. Without it, simple text progress is printed. Use --no-progress to disable progress reporting (marginally improves performance in some cases).

Use –threads to manually adjust the number of threads used in the operation. Otherwise, the number of threads will be automatically chosen.

To request SSE-B2 or SSE-C encryption for destination files, please set --destination-server-side-encryption=SSE-B2/SSE-C. The default algorithm is set to AES256 which can be changed with --destination-server-side-encryption-algorithm parameter. Using SSE-C requires providing B2_DESTINATION_SSE_C_KEY_B64 environment variable, containing the base64 encoded encryption key. If B2_DESTINATION_SSE_C_KEY_ID environment variable is provided, it’s value will be saved as sse_c_key_id in the uploaded file’s fileInfo.

Setting file retention settings requires the writeFileRetentions capability, and only works in bucket with fileLockEnabled=true. Providing --file-retention-mode requires providing --retain-until which has to be a future timestamp, in the form of an integer representing milliseconds since epoch. Leaving out these options results in a file retained according to bucket defaults.

Setting legal holds requires the writeFileLegalHolds capability, and only works in bucket with fileLockEnabled=true.

Use –incremental-mode to allow for incremental file uploads to safe bandwidth. This will only affect files, which have been appended to since last upload.

The --custom-upload-timestamp, in milliseconds-since-epoch, can be used to artificially change the upload timestamp of the file for the purpose of preserving retention policies after migration of data from other storage. The access to this feature is restricted - if you really need it, you’ll need to contact customer support to enable it temporarily for your account.

Requires capability:

• writeFiles

b2 upload-file [-h] [--content-type CONTENT_TYPE] [--sha1 SHA1] [--info INFO]
               [--custom-upload-timestamp CUSTOM_UPLOAD_TIMESTAMP]
               [--cache-control CACHE_CONTROL]
               [--content-disposition CONTENT_DISPOSITION]
               [--content-encoding CONTENT_ENCODING]
               [--content-language CONTENT_LANGUAGE] [--expires EXPIRES]
               [--min-part-size MIN_PART_SIZE] [--threads THREADS]
               [--no-progress]
               [--destination-server-side-encryption {SSE-B2,SSE-C}]
               [--destination-server-side-encryption-algorithm {AES256}]
               [--legal-hold {on,off}]
               [--file-retention-mode {compliance,governance}]
               [--retain-until TIMESTAMP] [--incremental-mode]
               bucketName localFilePath b2FileName

Positional Arguments

bucketName

name of the bucket where the file will be stored

localFilePath

path of the local file or stream to be uploaded

b2FileName

name file will be given when stored in B2

Named Arguments

--content-type

MIME type of the file being uploaded. If not set it will be guessed.

--sha1

SHA-1 of the data being uploaded for verifying file integrity

--info

additional file info to be stored with the file. Can be used multiple times for different information.

Default: []

--custom-upload-timestamp

overrides object creation date. Expressed as a number of milliseconds since epoch.

--cache-control

optional Cache-Control header, value based on RFC 2616 section 14.9, example: ‘public, max-age=86400’)

--content-disposition

optional Content-Disposition header, value based on RFC 2616 section 19.5.1, example: ‘attachment; filename=”fname.ext”’

--content-encoding

optional Content-Encoding header, value based on RFC 2616 section 14.11, example: ‘gzip’

--content-language

optional Content-Language header, value based on RFC 2616 section 14.12, example: ‘mi, en’

--expires

optional Expires header, value based on RFC 2616 section 14.21, example: ‘Thu, 01 Dec 2050 16:00:00 GMT’

--min-part-size

minimum part size in bytes

--threads

--no-progress

progress will not be reported

Default: False

--destination-server-side-encryption

Possible choices: SSE-B2, SSE-C

--destination-server-side-encryption-algorithm

Possible choices: AES256

Default: “AES256”

--legal-hold

Possible choices: on, off

--file-retention-mode

Possible choices: compliance, governance

--retain-until

--incremental-mode

Default: False