Use a share as S3 object storage

Your shares can be served as S3-compatible object storage. Anything that speaks S3 — rclone, the aws CLI, boto3, s3cmd, Cyberduck, most backup tools — can read them directly, streaming only the bytes it asks for.

This is the engine underneath mounting a share as a drive and the dataset streaming. This guide is for using it directly.

What it gives you

A share becomes a bucket. Files in it become objects. Range requests are served on demand from Usenet, so a client reading 1 MB out of a 50 GB object transfers about 1 MB.

Path-style addressing and SigV4 signing, which is what S3 clients expect. It is read-only: you cannot write into a share through it.

Turn it on

Settings → S3 / Object storage → Enable gateway.

You get an Endpoint, an Access key and a Secret key. Press Generate secret if there is not one yet, then Apply / Restart gateway.

It is off by default, deliberately — it opens a network port, so it turns on when you ask rather than because you installed the app.

For clients on other machines

Under Bind / advanced:

Public endpoint is the one people miss. Without it a client on another machine is handed an address that only means anything locally. The app warns you when it detects this.

If you set the bind host to 0.0.0.0, treat the secret key as a real secret. Anyone on your network who has it can read every share on this install.

Connect

The Settings page shows copy-paste recipes for rclone config and the aws CLI, filled in with your live endpoint. Use those rather than typing from here — they carry your actual address and port.

The shape of it, for orientation:

rclone config create uss s3 \
  provider=Other \
  endpoint=http://<your-endpoint>:8086 \
  access_key_id=<access key> \
  secret_access_key=<secret key> \
  force_path_style=true

rclone lsd uss:                       # your shares, as buckets
rclone ls uss:<share-id>              # objects in one
rclone mount uss:<share-id> /mnt/x --read-only

aws --endpoint-url http://<your-endpoint>:8086 s3 ls
aws --endpoint-url http://<your-endpoint>:8086 s3 cp s3://<share-id>/file.mkv .

Browse it in the app on the S3 Object Storage page, which lists buckets and objects without any client at all — useful for checking key names.

The complete reference, generated from the running build so it cannot go stale, is in the app at /api-docs/s3.

Scoped keys — the safer way to share access

The main access key can read every share. For giving one machine access to one share, mint a scoped key instead: read-only, limited to that share, and revocable on its own.

That is what the mount kits contain, and it is why a media PC can stream a library without holding anything that would let it read your other shares.

Scoped keys are listed in Settings → S3 / Object storage, where each can be revoked individually and immediately.

Use a scoped key for anything you hand to another machine. Use the main key only on the machine running UsenetShare.

What it is good and bad at

Good at:

• Streaming large files where the reader wants parts — video, disk images, datasets, archives read with an index
• Presenting a huge share to software that expects a filesystem or object store
• Read-only library access for media servers and backup tools

Bad at:

• Being written to. It is read-only, by design.
• Very many tiny random reads. Each one costs a network round trip, so a workload of a million 4 KB reads scattered at random is latency-bound and will feel slow. Sequential reads and reads of whole files are fast.
• Being a general-purpose S3 replacement. It serves shares. It is not durable storage you can put new objects into.

Connections are shared

The gateway draws on the same provider connection limit as downloading, so when both are active they get half each. The banner at the top of the app shows the split and lets you give either side everything.

Files already downloaded to this machine are served from disk and use no connections at all.

Streaming throughput is tunable with Settings → Performance → Streaming Prefetch Window — see Recommended settings.

When it goes wrong

SignatureDoesNotMatch. Almost always path-style not being forced. Set force_path_style=true in rclone, or the equivalent in your client. Some SDKs default to virtual-host style, which will not work here.

Connection refused from another machine. Bind host is 127.0.0.1. Set it to 0.0.0.0, set a Public endpoint, and Apply / Restart gateway.

The bucket list is empty. No shares imported yet, or the key is scoped to a share that has not finished importing.

A key stopped working. It was revoked, or it was scoped to a share that has been removed. Mint a new one.

Slow with many small files. Expected, and explained above. If those small files are things like artwork inside a share, they are usually grouped together on Usenet, so fetching one warms its neighbours and a directory of them is faster than the first file suggests.

Next

• Mount a share as a drive — this, with the mount done for you
• Automate a media library
• AI and datasets
• /api-docs/s3 in the app — the full wire reference