# Download and Environment Setup

## Runtime Environment

US3FS is implemented on top of FUSE (Linux) and WinFsp (Windows). Your machine must support FUSE or WinFsp.

Recommended environments:

- Linux
  - CentOS 7.0 or later (check via `cat /etc/redhat-release`)
  - Ubuntu 16.04 or later (check via `cat /etc/issue`)
- Windows
  - Download [WinFsp Installer](https://github.com/billziss-gh/winfsp/releases/download/v1.9/winfsp-1.9.21096.msi)
  - Install it following the [official instructions](http://www.secfs.net/winfsp/rel/)

> US3FS can run in both the DezaiCloud intranet and the public internet. In intranet environments, you can use an intranet endpoint to improve performance and stability.

## Downloads

- [Linux download](https://ufile-release.cn-bj.ufileos.com/us3fs/us3fs_2.0.3), or:

```shell
curl -o us3fs https://ufile-release.cn-bj.ufileos.com/us3fs/us3fs_2.0.3
```

- [Windows download](https://ufile-release.cn-bj.ufileos.com/us3fs/us3fs.exe)

## Configure Account Access

### Linux

Edit `/etc/us3fs/us3fs.yaml` and add the following content (create the directory if it doesn’t exist):

```
access_key: ************************************
secret_key: ************************************
endpoint: ufile.cn-north-02.ucloud.cn
hosts: []
```

Notes:

- Keep a single space after `:`.
- **access_key**: public key (Token key or API key). Must have overwrite-upload permissions.
- **secret_key**: private key (Token key or API key). Must have overwrite-upload permissions.
- **endpoint**: region endpoint (not a per-bucket domain).
- **hosts**: access point IP list. If fewer than 3 IPs are provided, it won’t take effect. Example: `hosts: [10.9.254.190, 117.50.123.23, 117.50.123.29, 117.50.123.8]`

> With `hosts`, unreachable IPs are removed in a 5s health-check cycle. Already-established TCP connections may take longer to fail due to exponential backoff (up to ~15 minutes by default). Consider setting `net.ipv4.tcp.retries2` (or `/proc/sys/net/ipv4/tcp_retries2`) to `6` to detect unreachable networks in ~25s.

To mount multiple buckets on a single machine, use `--passwd=passwd_file` to specify the credential file (default `/etc/us3fs/us3fs.yaml`).

After downloading, make it executable with `chmod +x us3fs`. Optionally move it into `/bin`:

```shell
chmod +x us3fs
./us3fs --passwd=passwd_file <bucket> <mountpoint>

mv us3fs /bin/us3fs
us3fs --passwd=passwd_file <bucket> <mountpoint>
```

### Windows

The configuration fields are the same as Linux; you can choose the config file path.

Example (in `cmd`):

```shell
# Switch to the drive containing the executable (example: D:)
C:\\Users\\Administrator> D:

# Enter the working directory
D:\\> cd us3fs

# Mount to drive X:
D:\\us3fs> us3fs.exe --passwd=us3fs.yaml -o debug --uid=0 --gid=0 --level=debug --readahead=32m <bucket> x:
```

> Note: On Windows, mounting currently runs in the foreground only.