Export Backups to Azure Files
Export to Azure Files from your Kilter instance.
Kilter can automatically export completed device backups to an Azure Files share (the Azure File Share remote export target). Unlike the generic SMB/CIFS export target, this integration talks to Azure over HTTPS using the Azure Storage SDK and authenticates with a Shared Access Signature (SAS) token. It does not use a storage account key or a username/password pair. With Kilter v9.1.0 and later, Access Keys are included as an alternate authentication method. Unlike SAS Tokens, Access Keys do not automatically expire. You can configure Access Keys in Azure in Storage Center → Storage Account → Access Keys.
This article covers how to configure the target correctly and how to read the most common error signatures found in general.log when exports fail.
Where It's Configured
Jobs → Exports → Remote Configuration, export target Azure File Share.
|
UI Field |
Meaning |
Example |
|---|---|---|
|
Storage Account Name |
The Azure Storage account name — short name only, no domain suffix |
|
|
SAS Token |
A Shared Access Signature token generated for that storage account (or file share) |
|
|
Access Key |
A secret key used to authenticate before granting access to data |
|
|
File Share Name |
The name of an existing share inside that storage account |
|
Kilter builds the connection endpoint from these values as:
https://<Storage Account Name>.file.core.windows.net/<File Share Name>
NOTE: Do not put the fully-qualified domain name in Storage Account Name. Enter only the account name — Kilter appends .file.core.windows.net automatically. See Error 1 below for what happens if this rule isn't followed.
Generate a Suitable SAS Token
In the Azure Portal, generate the SAS token from the storage account (Security + networking → Shared access signature) or scope it to the specific file share. Recommended settings:
- Allowed services — File
- Allowed permissions — Read, Write, Create, Delete, List
- Allowed protocols — HTTPS only
- Start/expiry — set an expiry far enough in the future for your retention/renewal process, and track the expiry date — Kilter does not warn you before a SAS token expires.
NOTE: Paste the token exactly as generated (a leading ? is optional and safe to include or omit).
Common Errors and Root Causes
Errors are logged in /backbox/app-server/logs/general.log on the management server.
Error 1: UnknownHostException — double domain suffix
ERROR ... com.azure.core.http.netty.NettyAsyncHttpClient.performLogging: java.net.UnknownHostException: <account>.file.core.windows.net.file.core.windows.net: Name or service not known
Cause: The Storage Account Name field contains the full hostname (<account>.file.core.windows.net) instead of just the account name. Because Kilter always appends .file.core.windows.net when building the endpoint, the suffix ends up duplicated, producing a hostname that can never resolve.
Fix: Edit the remote configuration and remove everything after the account name — enter only <account>, not <account>.file.core.windows.net.
Error 2: HTTP 401 NoAuthenticationInformation
ERROR ... com.azure.storage.file.share.ShareClient.performLogging: Status code 401, "<Error><Code>NoAuthenticationInformation</Code><Message>Server failed to authenticate the request. Please refer to the information in the www-authenticate header...</Message></Error>"
Cause: The request reached Azure successfully (this is a clean HTTP response, not a network or DNS failure), but Azure rejected the SAS token in the SAS Token field. This is almost always one of:
- The SAS token has expired.
- The SAS token was revoked (e.g. the storage account key it was signed with was regenerated).
- The token is missing required permissions (Read/Write/Create/Delete/List) or was restricted to HTTP onlywhile the request goes out over HTTPS (or vice versa).
- The token was truncated or altered when copy-pasted into the field (e.g. missing the
sig=parameter).
Fix: Generate a new SAS token with the recommended settings above and update the SAS Token field, then re-run the export (or wait for the next scheduled export) to confirm it clears.
Error 3: IllegalStateException: File share ... not found
Cause: The connection and authentication succeeded, but no share with the configured File Share Name exists in that storage account — usually a typo, or the share was deleted or renamed in Azure.
Fix: Confirm the exact share name in the Azure Portal (Storage account > File shares) and correct the File Share Name field to match.
Error 4: HTTP 403 AuthenticationFailed — "Signature did not match"
ERROR ... com.azure.storage.file.share.ShareClient.performLogging: If you are using aStorageSharedKeyCredential, and the server returned an error message that says 'Signature didnot match', you can compare the string to sign with the one generated by the SDK..
This particular line is generic SDK guidance text that Azure always logs with a Signature did not matchfailure. This error displays the same way regardless of which credential type is configured, so it doesn't by itself confirm the cause. Look for the Status code 403 / <Error><Code>AuthenticationFailed</Code> line logged around the same time for the actual error and RequestId.
Cause: Unlike Error 2 (no credential at all), this means a credential is being sent, but Azure recomputes the expected signature and it doesn't match. Check, in likelihood order:
- The SAS token was rotated/revoked after being saved in Kilter — e.g. the storage account key it was signed with was regenerated in Azure, which instantly invalidates every SAS token signed with that key, even ones that haven't reached their expiry.
- Copy/paste corruption — trailing whitespace, a partial paste that dropped part of the token (including the
sig=parameter), or a duplicated leading?. - The SAS was scoped to the wrong resource — e.g. generated against a specific file (
sr=f) or a different share, rather than the whole file share (sr=s). Kilter always uploads to the share root, so a SAS signed for a mismatched resource path will fail signature validation. - Clock skew on the appliance — SAS signatures are time-bound (
st=/se=); a large enough skew can surface as a signature failure rather than a clean expiry error.
Fix: Regenerate a fresh SAS token in the Azure Portal with the recommended settings above and re-paste it into the SAS Token field, then re-run the export. If it still fails, verify the token's allowed resource scope and check the appliance's time sync before regenerating again.
NOTE: directories are skipped, not failed.
Azure File Share export uploads files directly to the root of the share and does not support uploading folder structures. If any exported item is a directory, it's logged and skipped rather than causing the whole job to fail:
ERROR ... AzureExporter: File: <path> is a directory and will not be uploaded using Azure File Share
This is expected behavior, not a misconfiguration.
Troubleshooting Checklist
- Search
general.logfor recent Azure activity:
grep -i "azure\|ShareClient" /backbox/app-server/logs/general.log | tail -50
- Identify which error signature matches (see table below) and apply the corresponding fix.
- After changing Storage Account Name, SAS Token, or File Share Name, save the configuration under Jobs → Exports → Remote Configuration.
- Trigger a manual export (or wait for the next scheduled run) and re-check
general.logfor the same error. - If exports were failing for an extended period, note that Kilter does not automatically retry/backfill missed exports — historical backups that failed to export will need to be re-exported manually once the configuration is fixed.
|
Symptom in |
Likely field to check |
|---|---|
|
|
Storage Account Name |
|
HTTP |
SAS Token (expired/invalid/wrong permissions) |
|
|
File Share Name |
|
HTTP |
SAS Token (rotated/revoked, corrupted in copy-paste, or scoped to the wrong resource) |
|
SNMP/notification shows repeated |
Any of the above — check the ERROR line immediately above the notification in |
Related Articles
If you need additional information, contact support@backbox.com.