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). Default is 10.

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 --minPartSize 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 --noProgress to disable progress reporting (marginally improves performance in some cases).

Use –threads to manually adjust 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 --destinationServerSideEncryption=SSE-B2/SSE-C. The default algorithm is set to AES256 which can be changed with --destinationServerSideEncryptionAlgorithm 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 --fileRetentionMode requires providing --retainUntil 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 –incrementalMode 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] [--contentType CONTENTTYPE] [--sha1 SHA1]
               [--cache-control CACHE_CONTROL] [--info INFO]
               [--custom-upload-timestamp CUSTOM_UPLOAD_TIMESTAMP]
               [--minPartSize MINPARTSIZE] [--threads THREADS] [--noProgress]
               [--destinationServerSideEncryption {SSE-B2,SSE-C}]
               [--destinationServerSideEncryptionAlgorithm {AES256}]
               [--legalHold {on,off}]
               [--fileRetentionMode {compliance,governance}]
               [--retainUntil TIMESTAMP] [--incrementalMode]
               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

--contentType

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

--cache-control

--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.

--minPartSize

minimum part size in bytes

--threads

--noProgress

progress will not be reported

Default: False

--destinationServerSideEncryption

Possible choices: SSE-B2, SSE-C

--destinationServerSideEncryptionAlgorithm

Possible choices: AES256

Default: “AES256”

--legalHold

Possible choices: on, off

--fileRetentionMode

Possible choices: compliance, governance

--retainUntil

--incrementalMode

Default: False