File access & permissions
Path mappings govern file access for SFTP, SCP, FTP/FTPS, and SSH shell sessions in none (minimal) and legacy modes — in all of these, the user is confined to their mapped paths. They do not apply to the terminal shell mode; see SSH Access for details.
Each user sees a virtual filesystem assembled from path mappings — virtual paths that point to physical directories on the server, each with its own read/write/delete flags. The effective permissions on any file are the intersection of those flags and the OS-level permissions of the account that performs the I/O — the service account by default, or the impersonated Windows user when impersonation is enabled.
Path mappings
A path mapping consists of three parts:
- Virtual path — the directory the client sees when connected (e.g.
/,/shared,/data). - Physical path — the actual location on the server (e.g.
C:\Users\alexander,D:\Data, or a UNC path like\\dfs\shared). - File access flags — what operations are permitted within that mapping.
When a user logs in, they only see their mapped virtual paths. They cannot navigate outside of them.
A user with no root mapping (/) sees a synthetic root containing only their explicitly mapped subdirectories.
Example
Consider a user alexander with the following mappings:
| Virtual path | Physical path |
|---|---|
/ | C:\Users\alexander |
/shared | \\dfs\shared |
/data | D:\Data |
/logs | D:\Logs |
When alexander connects via SFTP, they see the contents of C:\Users\alexander at the root, with shared, data and logs appearing as subdirectories alongside any real subdirectories of C:\Users\alexander.
Mappings are configured per user via the Web Administration UI or the burusftp path CLI command.
Overlay limitation
You cannot overlay a virtual directory over a physical subdirectory that already exists under a parent mapping. For example, if / maps to C:\Data and C:\Data\reports exists on disc, mapping /reports to a different physical location will fail — the server refuses to resolve the ambiguity and the user will not be able to connect.
Permissions
Two layers control what a user can do within a mapping: the file access flags attached to the mapping, and the OS-level permissions of the Windows account that actually performs the I/O. The effective permissions are the intersection of both layers.
Each mapping carries a set of flags that restrict what the user can do:
| Flag | Name | Allows |
|---|---|---|
| R | Read | Download files, list directory contents |
| W | Write | Upload files, create or modify existing files |
| D | Delete | Remove files and directories |
| A | All | Shorthand for R + W + D |
Flags can be combined (e.g. RW for read/write without delete), and an empty flag set denies all access to the mapped path. Subdirectories within a mapping inherit the parent mapping's flags unless overridden by a child mapping — for example, A on / grants full access everywhere, but a separate mapping with R on /foo restricts that subdirectory to read-only.
On top of these flags, NTFS permissions still apply to every operation. By default, the server accesses files using the account the Windows service runs under — typically SYSTEM or a dedicated service account configured during installation. With Windows authentication and impersonation enabled, the server instead runs each file operation under the authenticated Windows user's identity, and NTFS permissions apply directly to that user.
SYSTEM account risk
The SYSTEM account has access to virtually everything on the local filesystem. NTFS permissions still apply, but since SYSTEM is granted access almost everywhere by default, the file access flags become the only practical restriction. For tighter control, use a dedicated service account with limited NTFS permissions, or enable impersonation.