Admin guide.

Farwing Server is the portal: accounts, storage locations, transfer tickets, packages, SSO, and audit. It runs in Free mode with no license. The usual install is Docker Compose on a Linux host with a public IP.

The portal

Once the server is running, each part of the product has its own guide.

• Files and storage spaces
• Packages and receive links
• Transfers, hot folders and sync, and event rules
• People and sign-in, including SAML and LDAP
• Appearance, email delivery, and email wording
• Virus scanning, speed check, and monitoring
• Plans and licenses and standby and backups

Ports

Two-command deploy

curl -fsSL https://farwing.io/compose.yml -o compose.yml
mkdir -p /data /srv/files
docker compose up -d

This compose file uses host networking and serves the portal on 8443. Open https://<hostname>:8443 and finish the setup wizard.

After the container is up

1. Open https://<hostname> (or :8443 for the standard compose).
2. Accept the browser warning if the certificate is still self-signed.
3. Setup wizard: admin account, then Choose how to start (Free mode, a 30-day trial, load a license, or request one), then storage location (often /files mapped from /srv/files) and hostname.
4. Replace the self-signed certificate: get a free one from Let’s Encrypt, or install your own, in the wizard or later in Admin → System → Network & HTTPS → Certificate.

Checklist

Transfer links

Farwing Desktop and the farwing cp --ticket command start each transfer with a ticket from the portal. Admin → System → Network & HTTPS → Transfer links sets how long a ticket may wait before its transfer starts: 5, 10, 15, 30 or 60 minutes, or any whole number of minutes up to 24 hours. The default is 10 minutes. A change applies to tickets issued after it.

• The time limit is for starting. A transfer that has started runs to the end however long it takes.
• An interrupted transfer continues with the same ticket for up to 24 hours after the ticket was first used. Only one transfer runs on a ticket at a time, and the ticket reaches only its own folder or file, for the person who asked for it, in its own direction.
• An upload ticket for a folder takes any number of files and folders in one transfer, up to 100,000 files and folders. Nothing already on the server is replaced, and the files appear only once the whole transfer has arrived. Each one is recorded in Admin → Security & audit → Audit log with who sent it, how many files and how many bytes.

Changing the ports

Admin → System → Network & HTTPS sets the portal port (TCP) and the transfer port (UDP, with TCP on the same number as a fallback). Any combination works, including the portal on 443 and transfers on 8443: UDP 8443 and TCP 443 are separate sockets. The page tries each new port before saving it, and the change applies when the server restarts. Links, tickets and recipient emails follow the ports in use.

A setting fixed by an environment variable (FARWING_WEB_PORT, FARWING_DATA_PORT, FARWING_HOSTNAME) is shown read-only, with the variable's name. Remove the variable from the compose file to manage the setting from the portal instead; to move its value into the config file first, run:

docker compose run --rm farwing set network.web_port 443
docker compose run --rm farwing set network.data_port 8443
docker compose run --rm farwing set web.hostname files.example.com

Ports below 1024, such as 443, need the NET_BIND_SERVICE capability. The image grants it and Docker keeps it by default; a compose file that drops capabilities adds it back:

    cap_drop: [ALL]
    cap_add: [NET_BIND_SERVICE]

Under systemd, set AmbientCapabilities=CAP_NET_BIND_SERVICE and CapabilityBoundingSet=CAP_NET_BIND_SERVICE. If the portal's port cannot be opened at start-up, the server opens it on 8443 instead and says why on the Network page, so you can choose another.

The portal’s certificate

On first start the server makes its own certificate. It encrypts the connection, but browsers show a warning and password managers do not offer to save sign-ins. Admin → System → Network & HTTPS → Certificate replaces it in one of two ways, and the new certificate is used from the next connection without a restart.

Free certificate from Let’s Encrypt

Let’s Encrypt issues certificates that every browser trusts. It needs:

• A public hostname set as the server’s address, such as files.example.com. An IP address, localhost, a single word, or a private name ending in .local, .lan or .internal cannot have one.
• A DNS record pointing at this server. An A record (and an AAAA record for IPv6) for the hostname, set to the server’s public address, for example files.example.com → 203.0.113.10. With Cloudflare, keep it DNS only.
• TCP 443 or TCP 80 reachable from the internet. Let’s Encrypt checks on those two ports only. With the portal on 443 nothing else is needed. With the portal on 8443, the server opens port 80 for the check and redirects any other visitor there to HTTPS.

Before offering the certificate the page checks all three: it looks the name up, compares it with the address farwing.io sees this server at, and tries the ports from the internet. Anything that would stop Let’s Encrypt is shown in red with the exact change to make. Enter a contact email if you want Let’s Encrypt’s notices, accept the Subscriber Agreement, and choose Get a free certificate. The page follows the request through checking, requesting, validating and installed, which usually takes under a minute.

Let’s Encrypt certificates last about 90 days. With Renew automatically on (the default), the server renews when a third of the certificate’s life is left, retries with increasing gaps if that fails, and records each attempt in Admin → Security & audit → Audit log. Renew now renews straight away.

Your own certificate

Choose Use your own certificate, then paste or choose the certificate chain (the server certificate first, then the intermediates) and the private key, both in PEM format. RSA, ECDSA and Ed25519 keys are accepted; the key must not have a password. Check shows the issuer, the names it covers and its dates, and refuses a key that does not match, a certificate that has expired, or one that is not valid yet. Nothing changes until it passes, so a rejected upload leaves the current certificate in place. A certificate that does not cover the server’s address can still be installed, with a warning. To use a .pfx file, convert it first:

openssl pkcs12 -in server.pfx -nokeys -out chain.pem
openssl pkcs12 -in server.pfx -nocerts -nodes -out key.pem

Your own certificate is not renewed automatically; install the next one before it expires.

Expiry warnings and going back

The Certificate section shows the issuer, the names, the issue and expiry dates and the days left. When a certificate is within 14 days of expiring, or a renewal has failed, administrators see a banner on every page and, if email is set up, get a message. Go back to the self-signed certificate returns to the server’s own certificate and deletes the installed one.

Restart and maintenance

Admin → System → Health → Restart applies saved settings (address, ports, certificate). Running transfers pause and continue from where they stopped, and the page reloads once the server is back. In Docker the server exits and the container's restart policy starts it again, so keep restart: unless-stopped in the compose file (--restart unless-stopped with docker run). Under systemd, use Restart=always. A server started by hand restarts itself in place. FARWING_RESTART=exit or exec chooses explicitly.

While maintenance is on, new uploads, transfers and packages are paused for everyone, including administrators. Only administrators can sign in. Transfers already running carry on, or can be paused when you turn it on. Everyone sees a banner with your note, and maintenance stays on through restarts until you turn it off. Both actions are in the audit log.

Scheduled work waits too. Hot folders and sync jobs do not start new transfers, and event rules that send to another Farwing server or send a package stay queued. Nothing is lost: they start on their own within a minute of maintenance being turned off. Event rules that only run a command, call a webhook, send an email or work on files carry on as usual.

Storing files in an S3 bucket

Admin → Storage → Locations → Add a storage location → S3 bucket connects Farwing to Amazon S3 or any S3-compatible service. Choose the service and Farwing fills in its endpoint pattern, region and addressing style:

Then give the bucket name and, optionally, a remote folder: Farwing keeps its files under that path in the bucket. For credentials, create an access key that can read, write, list and delete in that bucket only, and enter the access key ID and secret access key. The secret is stored encrypted on this server and is never shown again; when you edit the storage later it reads Saved, and it stays in place unless you choose Change key. When Farwing runs on AWS with an instance role, or with credentials in its environment, choose This server's environment or instance role instead and no key is stored at all.

Test connection checks exactly what is in the form, including a new secret you have not saved yet, by listing the remote folder. It writes nothing. When something is wrong it shows what the service answered: an unknown access key, a secret that does not match, a bucket that does not exist, a bucket in another region (with the right one), or a key that may not list the folder.

Objects stay private: Farwing never makes them public, and people reach files through Farwing and the access you grant. Tick Read only to let people browse and download without Farwing writing anything to the bucket. Endpoints use https://. Plain http:// is accepted only for a service on the same machine or a private network address, such as a MinIO container beside Farwing, and the form says so while it is in use. The bucket and the remote folder are fixed once saved, because access you grant points inside them; the name, region, endpoint, credentials and read-only setting can be changed at any time.

Storage locations and spaces

Admin → Storage has two tabs. Locations lists your storage locations, where files physically live: a folder on this server or an S3 bucket, with its credentials, health and speed. Spaces are how those files are served to people: a space opens a whole location or one folder in it, under a name of its own, and is what people see on their Files page. A shared space has its own list of people and groups. A personal space gives everyone their own private folder.

Access is given on spaces only. After you add a storage location, Farwing offers to share it as a space straight away. Name the space, then pick the people and groups who get it. Each location lists the spaces that use it, and a location that no space uses says so, so storage is never set up with nothing for anyone to open.

Who can reach which space

Admins reach every space. Everyone else sees only the spaces they have been given. On Admin → Storage → Spaces, choose Access on a space to see who has it and to give or remove access for people and groups, for the whole space or for one folder in it. You can pick several people and groups at once. A group grant reaches every member of the group, and Admin → User management → Groups shows the same grants from the group's side.

Access given on a location before spaces existed keeps working. When the server starts, each such grant is listed on the space that holds its folder. A grant that no space holds gets a space over the whole location, named after it. Nobody gains or loses access, and the new space appears under Spaces, where you can rename it or change who has it.

Removing a space first shows who would lose access, by name and with a count, and who keeps it because another space also holds their folder. When anyone would lose access, you type the space's name to confirm. Access another space holds moves to that space; everything else given on the space is removed, and one entry in Admin → Security & audit → Audit log lists it all. The files stay on the storage location, untouched. A personal space cannot be removed while people with access to the folders around it would then be able to open its private folders; take that access away first.

The server checks access on every request: the Files page, browser uploads and downloads, transfer tickets for Farwing Desktop and the farwing command, and packages. A change applies to the next request, and every grant and removal is recorded in Admin → Security & audit → Audit log.

Transfers

The Transfers page lists uploads and downloads with who moved them, how (browser, Farwing Desktop, the farwing command, automation with an API key, or a package link), how much, how fast and how it ended. The figures at the top count every transfer that matches the filters, not just the page on screen.

Administrators see every transfer and can switch between Mine and Everyone's. Everyone else sees a transfer when they started it, when it used a transfer link or package they made, or when it went into or out of a folder they can read, through their own access or a group they belong to. Access to projects covers projects and everything inside it. Seeing a transfer does not let you stop it: only the person who started it, or an administrator, can pause, resume or cancel it.

Filter by date, status, direction, method, storage, package, group (administrators), and by who started it, who made the link, who uploaded it or who downloaded it, including people without an account who collected a package. Search matches file names, folders, people and package subjects. Filters, sorting and the page are kept in the address, so a link you copy opens the same view. Choose a transfer to see all its files, where it came from and went to, any error, and the actions it allows.

Traffic limits and usage

Admin → Transfers → Traffic limits sets speed and how many transfers may run at once, for the whole server and (with a Team license) per user, group and external recipient. Business adds schedules, group priority and per-job limits. Admin → Transfers → Usage shows live copies, history charts, CSV export, scheduled email and a Prometheus metrics feed.

Usage is stored in the same SQLite database. Per-minute rows are kept 30 days (about 170 MB for 50 series). Per-hour rows are kept forever: about 17 MB per year for 50 series. Free mode shows the last 30 days; older hour rows stay on disk and come back when a license is loaded.

Packages

A package sends files that are already on the server to people outside it. On Packages, choose Send a package, pick a storage, then tick the files and folders to send or choose Everything in this storage. A folder includes everything inside it. Add recipients by email address, choose when the links stop working (7 days, 30 days, a date of your own, or never if the server allows it), and optionally set a passcode. You can also start a package from a selection on the Files page.

Each recipient gets their own link by email. The email says whether a passcode is needed but never contains it, so tell the recipient the passcode another way. Opening the link needs no account. The recipient can download everything as one ZIP or file by file in the browser, receive the whole package in Farwing Desktop as one transfer with its folders, or copy one command that downloads the whole package:

farwing get https://files.example.com/r/TOKEN

To get only some of the files, the recipient ticks them on the page and downloads the selection as a ZIP, opens it in Farwing Desktop, or copies a command for just those files. Several files fetched together count as one collection.

Packages lists the packages that are still active, with how many people collected them. Open one to see each recipient, when they first opened the link, and every download with its time, file and method. Revoke a single recipient's link or the whole package at any time; the link stops working on the next request. Expired and revoked packages move to History, which keeps the full record of who received what and who revoked it. Admins can switch to Everyone's to see every package on the server. Creating, downloading and revoking are also recorded in Admin → Security & audit → Audit log.

API keys

Profile → API keys makes a key for a script or another system. Each key expires after 1 day, 7 days, 30 days (the default), a custom number of days or date, or never. A key that never expires keeps working until someone revokes it, so prefer an expiry and make a new key when it runs out. Admin → Security & audit → API keys sets the longest life a key may have and whether keys that never expire are allowed; the form offers only what the policy allows. Revoked and expired keys are tucked away under Show revoked and expired keys.

The API is part of every paid plan, with no limit on keys. In Free mode, /api/v1 calls return HTTP 402, except GET /api/v1/license and the health check. Keys are kept and work again once a license with the API is loaded.

Checking the firewall from the internet

Admin → System → Network & HTTPS → Check from the internet asks farwing.io to connect to this server. Farwing sends the server's public address, the port numbers, and a one-time ticket for a small test file of random bytes, and nothing else. farwing.io only connects to the address the request comes from, so it cannot be pointed at anyone else's machine. The test file is deleted afterwards.

TCP ports are tried with a connection: Open, Refused (the machine answered but nothing accepted the connection) or No answer (a cloud security group or firewall is dropping it). The UDP transfer port is tried by downloading the test file over UDP only, with no fallback to TCP: Open shows its size and how long it took, No answer means nothing reached the port, and One way means UDP reached the server but its replies did not get back, so outbound UDP is blocked.

Transfers at full speed is the last row. The command is on that row. Make a test command makes a one-time command that downloads the same kind of test file from wherever you run it, which proves UDP from that network:

farwing cp --ticket … --transport udp .

The command works once, for one minute, and saves farwing-udp-test.bin in the current folder. A finished download turns that same row to Open.

License

Admin → System → License shows the plan, speed, features, users and jobs allowed, the expiry date and the install ID, and each page that needs a feature says so before you edit it.

A new server starts in Free mode. Start a 30-day trial with every feature from Admin → System → License or the setup wizard; the server contacts license.farwing.io only when you click it. When a license or trial ends, the server drops to Free mode: nothing is deleted and nobody is locked out. Plans and licenses covers trials, the request form, loading a license, the install ID and Free mode in full.

Related

• Getting started for the free client
• Plans and licenses for trials, Free mode and requesting a license
• Failover with a standby server for nightly backups and restore
• API reference for automation
• Monitoring for the Prometheus feed
• Product page on farwing.io

Farwing docs · farwing.io