diff --git a/locales/en.yml b/locales/en.yml index 83943acd..804a2f9d 100644 --- a/locales/en.yml +++ b/locales/en.yml @@ -9939,6 +9939,186 @@ tools: get-a-random-tool-from-the-list: Get a random tool from the list. random-tool: Random tool tools: Tools + restic-command-generator: + title: Restic Command Generator + description: "Generate restic CLI commands to restore a Backrest or plain restic + repository: a whole snapshot, only some files, or a browsable mount." + texts: + intro: "Generator only: nothing runs here and nothing you type leaves your + browser. Describe your repository, pick what you need to recover, and copy + the shell snippet." + title-repository: Repository + label-backend: Backend + backend-s3: S3 compatible (Backblaze B2, MinIO, Wasabi, AWS…) + backend-b2: Backblaze B2 (native) + backend-local: Local path or mounted disk + backend-sftp: SFTP + backend-rest: restic REST server + backend-rclone: Rclone + backend-azure: Azure Blob Storage + backend-gs: Google Cloud Storage + backend-raw: Other (raw repository URI) + label-local-path: Repository path + label-endpoint: Endpoint + label-bucket: Bucket + label-prefix: Path in the bucket + label-region: Region (optional) + label-user: User + label-host: Host + label-port: Port (optional) + label-path: Repository path + label-url: Server URL + label-remote: Rclone remote and path + label-container: Container + label-raw-repository: Repository URI + label-repository-mode: Repository passed as + repository-flag: -r flag on every command + repository-env: RESTIC_REPOSITORY environment variable + label-repository-uri: Repository URI + label-password: Repository password + password-prompt: Prompt for it in the shell (read -rs, stays out of the history) + password-file: --password-file + password-command: --password-command + password-placeholder: RESTIC_PASSWORD export with a placeholder + password-none: Already set in my environment + label-password-file: Password file + label-password-command: Password command + label-credentials: Backend credentials + credentials-prompt: Prompt for the secret in the shell + credentials-placeholder: Export them with placeholders + credentials-none: Already set in my environment + label-account-id: Key ID / account name + hint-secrets: 'No secret is ever put in the generated command: the prompt + options read them into your shell with "read -rs" so they stay out of your + history.' + title-operation: What do you want to do? + operation-restore: restore — write files from a snapshot back to disk + operation-dump: dump — stream one file or folder out of a snapshot + operation-mount: mount — browse the repository as a filesystem + operation-snapshots: snapshots — list the snapshots of the repository + operation-ls: ls — list the files inside a snapshot + operation-find: find — locate a file across snapshots + operation-diff: diff — compare two snapshots + operation-check: check — verify the integrity of the repository + operation-stats: stats — size of a snapshot or of the repository + operation-unlock: unlock — remove stale locks + title-snapshot: Snapshot selection + label-snapshot-id: Snapshot ID + label-subfolder: Only this subfolder of the snapshot + label-plan: Backrest plan ID + label-instance: Backrest instance ID + label-filter-host: Host + label-tags: Extra tags + placeholder-tag: manual + label-filter-paths: Paths + placeholder-path: /home/me/documents + hint-tags: Backrest tags the snapshots it creates with "plan:" and + "created-by:" followed by the plan and the instance IDs. Tags inside a + single --tag are ANDed while repeated --tag flags are ORed, so the plan + and the instance stay in one flag and each extra tag gets its own. + title-restore-options: Restore options + label-target: Target directory + label-include: Restore only these paths or patterns + placeholder-include: /home/me/documents/**/*.pdf + label-exclude: Exclude these paths or patterns + placeholder-exclude: "**/node_modules" + label-overwrite: Overwrite existing files + overwrite-default: restic default (always) + overwrite-always: always + overwrite-if-changed: if-changed + overwrite-if-newer: if-newer + overwrite-never: never + label-case-insensitive: Case insensitive patterns + label-dry-run: Dry run + label-verify: Verify restored files + label-sparse: Write sparse files + label-delete: Delete files missing from the snapshot + title-dump-options: Dump options + label-dump-path: File or folder inside the snapshot + label-archive: Archive format + archive-none: Raw file + archive-tar: tar + archive-zip: zip + label-output-file: Redirect to a local file (optional) + hint-dump: dump streams a single file or folder straight out of the repository, + so you do not have to restore a whole snapshot to get one config file + back. + title-mount-options: Mount options + label-mount-point: Mount point + label-allow-other: Allow other users to access the mount + title-ls-options: List options + label-ls-directory: Directory to list (optional) + label-long: Long listing + label-recursive: Recursive + title-find-options: Find options + label-find-pattern: Pattern + label-restrict-snapshot: Search only the selected snapshot + title-diff-options: Diff options + label-diff-snapshot: Compare with snapshot + label-metadata: Report metadata changes too + title-snapshots-options: Snapshots options + label-compact: Compact output + title-check-options: Check options + label-read-data-subset: Read data subset + label-read-data: Read and verify every pack file + label-check-unused: Report unused blobs + label-with-cache: Use the existing cache + title-stats-options: Stats options + label-stats-mode: Counting mode + stats-restore-size: restore-size — size of a restore + stats-files-by-contents: files-by-contents — unique files + stats-raw-data: raw-data — size before deduplication + stats-blobs-per-file: blobs-per-file + label-stats-all: All snapshots + title-unlock-options: Unlock options + label-remove-all: Remove every lock, including the ones in use + title-global-options: Global options + label-cache-dir: Cache directory + label-limit-download: Download limit (KiB/s) + label-retry-lock: Retry a locked repository for + label-extra-options: Backend options (-o) + placeholder-extra-option: s3.connections=4 + label-extra-arguments: Extra arguments (appended as-is) + label-no-lock: --no-lock + label-no-cache: --no-cache + label-insecure-tls: --insecure-tls + label-json: --json + label-quiet: --quiet + label-verbose: --verbose + title-output: Generated command + label-include-environment: Include the environment setup + label-multiline: One argument per line + button-reset: Reset to defaults + warning-history: "Placeholder exports stay in your shell history once filled in: + prefer the prompt options, or clear the history afterwards." + warning-target: restore recreates the full path of every file under the + target directory, so /etc/hosts ends up in the etc/hosts subfolder of the + target. + warning-delete: --delete removes the files of the target directory that are not + in the snapshot. Try it with --dry-run first. + warning-restic-version: --dry-run, --delete and --overwrite require restic 0.17 or newer. + warning-mount: mount needs FUSE, exposes the snapshots read-only, and keeps + running until you stop it with Ctrl-C. + title-walkthrough: Recovery walkthrough + hint-walkthrough: The usual sequence when the repository is all that is left, + built from the settings above. + walkthrough-snapshots: List the snapshots of the repository + walkthrough-find: Find which snapshot holds the file you need + walkthrough-ls: List the files of the chosen snapshot + walkthrough-restore: Restore only the files you need + walkthrough-mount: Or browse the repository and copy files out by hand + title-backrest: Backrest cheat sheet + table-item: Item + table-value: Default path or format (Docker image between parentheses) + backrest-config: Config file, holding the repository URI, its password and the + backend environment variables + backrest-data: Data directory + backrest-binary: Restic binary downloaded by Backrest + backrest-plan-tag: Tag identifying the plan + backrest-instance-tag: Tag identifying the instance + hint-backrest: "A Backrest repository is a plain restic repository: if the web + UI is gone, read the URI and the password out of config.json and drive it + with the restic binary Backrest already downloaded." external-self-hosted-required: External Self Hosted Required collapsibleToolMenu: text: diff --git a/src/tools/restic-command-generator/index.ts b/src/tools/restic-command-generator/index.ts new file mode 100644 index 00000000..49fba05e --- /dev/null +++ b/src/tools/restic-command-generator/index.ts @@ -0,0 +1,25 @@ +import { defineTool } from '../tool'; +import { translate as t } from '@/plugins/i18n.plugin'; + +export const tool = defineTool({ + name: t('tools.restic-command-generator.title'), + path: '/restic-command-generator', + description: t('tools.restic-command-generator.description'), + keywords: [ + 'restic', + 'backrest', + 'restore', + 'backup', + 'snapshot', + 'repository', + 'command', + 'generator', + 's3', + 'backblaze', + 'b2', + ], + component: () => import('./restic-command-generator.vue'), + icon: defineAsyncComponent(() => import('@vicons/tabler/es/DatabaseImport')), + createdAt: new Date('2026-09-11'), + category: 'Network', +}); diff --git a/src/tools/restic-command-generator/restic-command-generator.service.test.ts b/src/tools/restic-command-generator/restic-command-generator.service.test.ts new file mode 100644 index 00000000..504dc415 --- /dev/null +++ b/src/tools/restic-command-generator/restic-command-generator.service.test.ts @@ -0,0 +1,354 @@ +import { describe, expect, it } from 'vitest'; +import { + type ResticCommandConfig, + buildEnvironmentLines, + buildRepositoryUri, + buildResticCommand, + buildResticScript, + buildSnapshotArgument, + buildTagFilters, + defaultResticCommandConfig, + quoteShellArg, +} from './restic-command-generator.service'; + +function makeConfig(overrides: Partial = {}): ResticCommandConfig { + return { ...defaultResticCommandConfig, ...overrides }; +} + +const b2Repository = 's3:s3.us-west-004.backblazeb2.com/my-backup-bucket/backrest'; + +describe('restic-command-generator.service', () => { + describe('quoteShellArg', () => { + it('leaves shell-safe values untouched', () => { + expect(quoteShellArg('/mnt/restore')).toBe('/mnt/restore'); + expect(quoteShellArg('plan:daily-docs')).toBe('plan:daily-docs'); + expect(quoteShellArg('~/restore')).toBe('~/restore'); + expect(quoteShellArg(b2Repository)).toBe(b2Repository); + }); + + it('quotes globs so the shell does not expand them', () => { + expect(quoteShellArg('/home/me/**/*.pdf')).toBe("'/home/me/**/*.pdf'"); + expect(quoteShellArg('my documents')).toBe("'my documents'"); + }); + + it('escapes single quotes', () => { + expect(quoteShellArg("/data/o'brien/notes")).toBe("'/data/o'\\''brien/notes'"); + }); + + it('quotes empty values', () => { + expect(quoteShellArg('')).toBe("''"); + }); + }); + + describe('buildRepositoryUri', () => { + it('builds a local repository path', () => { + expect(buildRepositoryUri(makeConfig({ backend: 'local', localPath: '/mnt/backups/repo' }))).toBe( + '/mnt/backups/repo', + ); + }); + + it('builds an S3 compatible uri and drops the scheme of the endpoint', () => { + expect(buildRepositoryUri(makeConfig())).toBe(b2Repository); + expect( + buildRepositoryUri( + makeConfig({ + s3Endpoint: 'https://s3.eu-central-003.backblazeb2.com/', + s3Bucket: '/bucket/', + s3Prefix: '/nested/path/', + }), + ), + ).toBe('s3:s3.eu-central-003.backblazeb2.com/bucket/nested/path'); + }); + + it('builds a Backblaze B2 native uri', () => { + expect(buildRepositoryUri(makeConfig({ backend: 'b2', b2Bucket: 'bucket', b2Prefix: 'backrest' }))).toBe( + 'b2:bucket:backrest', + ); + expect(buildRepositoryUri(makeConfig({ backend: 'b2', b2Bucket: 'bucket', b2Prefix: '' }))).toBe('b2:bucket:/'); + }); + + it('builds sftp uris, switching to the url form when a port is given', () => { + expect( + buildRepositoryUri( + makeConfig({ backend: 'sftp', sftpUser: 'backup', sftpHost: 'nas.lan', sftpPath: '/srv/repo' }), + ), + ).toBe('sftp:backup@nas.lan:/srv/repo'); + expect( + buildRepositoryUri( + makeConfig({ + backend: 'sftp', + sftpUser: 'backup', + sftpHost: 'nas.lan', + sftpPort: '2222', + sftpPath: '/srv/repo', + }), + ), + ).toBe('sftp://backup@nas.lan:2222//srv/repo'); + }); + + it('builds the remaining backend uris', () => { + expect(buildRepositoryUri(makeConfig({ backend: 'rest', restUrl: 'https://restic.lan:8000/' }))).toBe( + 'rest:https://restic.lan:8000/', + ); + expect(buildRepositoryUri(makeConfig({ backend: 'rclone', rcloneRemote: 'b2:bucket/repo' }))).toBe( + 'rclone:b2:bucket/repo', + ); + expect( + buildRepositoryUri(makeConfig({ backend: 'azure', azureContainer: 'container', azurePrefix: 'backrest' })), + ).toBe('azure:container:/backrest'); + expect(buildRepositoryUri(makeConfig({ backend: 'gs', gsBucket: 'bucket', gsPrefix: '' }))).toBe('gs:bucket:/'); + expect(buildRepositoryUri(makeConfig({ backend: 'raw', rawRepository: 'swift:container:/repo' }))).toBe( + 'swift:container:/repo', + ); + }); + }); + + describe('buildSnapshotArgument', () => { + it('defaults to latest', () => { + expect(buildSnapshotArgument(makeConfig({ snapshotId: '' }))).toBe('latest'); + }); + + it('appends the subfolder with a leading slash', () => { + expect(buildSnapshotArgument(makeConfig({ snapshotId: '4bba301e', snapshotSubfolder: 'home/me' }))).toBe( + '4bba301e:/home/me', + ); + expect(buildSnapshotArgument(makeConfig({ snapshotId: 'latest', snapshotSubfolder: '/etc' }))).toBe( + 'latest:/etc', + ); + }); + }); + + describe('buildTagFilters', () => { + it('ands the Backrest plan and instance into a single tag filter', () => { + expect(buildTagFilters(makeConfig({ backrestPlan: 'daily-docs', backrestInstance: 'homelab' }))).toEqual([ + 'plan:daily-docs,created-by:homelab', + ]); + }); + + it('keeps extra tags as separate (ORed) filters', () => { + expect(buildTagFilters(makeConfig({ backrestPlan: 'daily-docs', tags: ['manual', ' ', 'pre-upgrade'] }))).toEqual( + ['plan:daily-docs', 'manual', 'pre-upgrade'], + ); + }); + }); + + describe('buildResticCommand', () => { + it('generates a full restore of the latest snapshot', () => { + expect(buildResticCommand(makeConfig())).toBe(`restic -r ${b2Repository} restore --target /mnt/restore latest`); + }); + + it('generates a partial restore filtered on a Backrest plan', () => { + const command = buildResticCommand( + makeConfig({ + backrestPlan: 'daily-docs', + backrestInstance: 'homelab', + includes: ['/home/me/documents/**/*.pdf'], + excludes: ['/home/me/documents/tmp'], + target: '/mnt/restore', + dryRun: true, + verify: true, + }), + ); + + expect(command).toBe( + `restic -r ${b2Repository} restore --target /mnt/restore ` + + `--include '/home/me/documents/**/*.pdf' --exclude /home/me/documents/tmp ` + + '--verify --dry-run --tag plan:daily-docs,created-by:homelab latest', + ); + }); + + it('uses the case insensitive pattern flags when asked', () => { + const command = buildResticCommand( + makeConfig({ includes: ['*.PDF'], excludes: ['*.tmp'], caseInsensitivePatterns: true }), + ); + + expect(command).toContain("--iinclude '*.PDF'"); + expect(command).toContain("--iexclude '*.tmp'"); + }); + + it('restores a subfolder of a given snapshot with overwrite and delete', () => { + const command = buildResticCommand( + makeConfig({ + snapshotId: '4bba301e', + snapshotSubfolder: '/var/lib/postgresql', + target: '/srv/restore', + overwrite: 'if-newer', + deleteExtraneous: true, + sparse: true, + }), + ); + + expect(command).toBe( + `restic -r ${b2Repository} restore --target /srv/restore --overwrite if-newer --delete --sparse ` + + '4bba301e:/var/lib/postgresql', + ); + }); + + it('dumps a single file and redirects it to a local file', () => { + const command = buildResticCommand( + makeConfig({ + operation: 'dump', + dumpPath: '/etc/nginx/nginx.conf', + dumpOutputFile: './nginx.conf', + backrestPlan: 'daily-docs', + }), + ); + + expect(command).toBe( + `restic -r ${b2Repository} dump --tag plan:daily-docs latest /etc/nginx/nginx.conf > ./nginx.conf`, + ); + }); + + it('dumps a folder as a tar archive', () => { + expect( + buildResticCommand(makeConfig({ operation: 'dump', dumpArchive: 'tar', dumpPath: '/home/me/documents' })), + ).toBe(`restic -r ${b2Repository} dump --archive tar latest /home/me/documents`); + }); + + it('generates the snapshots, ls, find, diff, check, stats and unlock commands', () => { + expect(buildResticCommand(makeConfig({ operation: 'snapshots', backrestPlan: 'daily-docs' }))).toBe( + `restic -r ${b2Repository} snapshots --tag plan:daily-docs`, + ); + expect( + buildResticCommand(makeConfig({ operation: 'ls', lsRecursive: true, lsDirectory: '/home/me/documents' })), + ).toBe(`restic -r ${b2Repository} ls --long --recursive latest /home/me/documents`); + expect( + buildResticCommand( + makeConfig({ operation: 'find', findPattern: '*.kdbx', caseInsensitivePatterns: true, findLong: true }), + ), + ).toBe(`restic -r ${b2Repository} find --long --ignore-case '*.kdbx'`); + expect( + buildResticCommand(makeConfig({ operation: 'find', findRestrictToSnapshot: true, snapshotId: '4bba301e' })), + ).toBe(`restic -r ${b2Repository} find --snapshot 4bba301e '*.conf'`); + expect( + buildResticCommand(makeConfig({ operation: 'diff', snapshotId: '4bba301e', diffSnapshotId: 'latest' })), + ).toBe(`restic -r ${b2Repository} diff 4bba301e latest`); + expect(buildResticCommand(makeConfig({ operation: 'check', checkReadDataSubset: '5%' }))).toBe( + `restic -r ${b2Repository} check --read-data-subset=5%`, + ); + expect(buildResticCommand(makeConfig({ operation: 'stats', statsAllSnapshots: true }))).toBe( + `restic -r ${b2Repository} stats --mode restore-size`, + ); + expect(buildResticCommand(makeConfig({ operation: 'unlock', unlockRemoveAll: true }))).toBe( + `restic -r ${b2Repository} unlock --remove-all`, + ); + }); + + it('mounts the repository on a mount point', () => { + expect(buildResticCommand(makeConfig({ operation: 'mount', mountPoint: '/mnt/restic', allowOther: true }))).toBe( + `restic -r ${b2Repository} mount --allow-other /mnt/restic`, + ); + }); + + it('adds global options, host and path filters', () => { + const command = buildResticCommand( + makeConfig({ + operation: 'snapshots', + host: 'homelab', + paths: ['/home/me/documents'], + noLock: true, + noCache: true, + limitDownload: '2048', + retryLock: '5m', + insecureTls: true, + extraOptions: ['s3.connections=4'], + json: true, + }), + ); + + expect(command).toBe( + `restic -r ${b2Repository} --no-cache --no-lock --limit-download 2048 --retry-lock 5m --insecure-tls ` + + '-o s3.connections=4 --json snapshots --host homelab --path /home/me/documents', + ); + }); + + it('only adds --no-lock on read-only commands', () => { + expect(buildResticCommand(makeConfig({ operation: 'ls', noLock: true }))).toContain('--no-lock'); + expect(buildResticCommand(makeConfig({ operation: 'check', noLock: true }))).not.toContain('--no-lock'); + }); + + it('uses the password flags instead of environment variables when asked', () => { + expect( + buildResticCommand(makeConfig({ passwordMode: 'file', passwordFile: '/root/.restic-password' })), + ).toContain('--password-file /root/.restic-password'); + expect( + buildResticCommand(makeConfig({ passwordMode: 'command', passwordCommand: 'pass show restic/repo' })), + ).toContain("--password-command 'pass show restic/repo'"); + }); + + it('omits the repository flag when the repository comes from the environment', () => { + expect(buildResticCommand(makeConfig({ repositoryMode: 'env', operation: 'snapshots' }))).toBe( + 'restic snapshots', + ); + }); + + it('appends free-form extra arguments verbatim', () => { + expect(buildResticCommand(makeConfig({ operation: 'snapshots', extraArguments: '--group-by host,tags' }))).toBe( + `restic -r ${b2Repository} snapshots --group-by host,tags`, + ); + }); + + it('can break the command over several lines', () => { + expect(buildResticCommand(makeConfig({ operation: 'snapshots' }), { multiline: true })).toBe( + `restic \\\n -r ${b2Repository} \\\n snapshots`, + ); + }); + }); + + describe('buildEnvironmentLines', () => { + it('prompts for the secrets by default', () => { + expect(buildEnvironmentLines(makeConfig())).toEqual([ + "read -rsp 'RESTIC_PASSWORD: ' RESTIC_PASSWORD && echo && export RESTIC_PASSWORD", + "export AWS_ACCESS_KEY_ID=''", + "read -rsp 'AWS_SECRET_ACCESS_KEY: ' AWS_SECRET_ACCESS_KEY && echo && export AWS_SECRET_ACCESS_KEY", + ]); + }); + + it('exports placeholders when literal exports are chosen', () => { + expect( + buildEnvironmentLines( + makeConfig({ + backend: 'b2', + repositoryMode: 'env', + passwordMode: 'placeholder', + credentialsMode: 'placeholder', + accountId: '0026b1c', + }), + ), + ).toEqual([ + 'export RESTIC_REPOSITORY=b2:my-backup-bucket:backrest', + "export RESTIC_PASSWORD=''", + 'export B2_ACCOUNT_ID=0026b1c', + "export B2_ACCOUNT_KEY=''", + ]); + }); + + it('exports the region when one is set', () => { + expect(buildEnvironmentLines(makeConfig({ s3Region: 'us-west-004', credentialsMode: 'placeholder' }))).toContain( + 'export AWS_DEFAULT_REGION=us-west-004', + ); + }); + + it('emits nothing when secrets are handled outside of the snippet', () => { + expect(buildEnvironmentLines(makeConfig({ passwordMode: 'none', credentialsMode: 'none' }))).toEqual([]); + }); + + it('emits no credentials for backends that do not need any', () => { + expect(buildEnvironmentLines(makeConfig({ backend: 'local', passwordMode: 'none' }))).toEqual([]); + }); + }); + + describe('buildResticScript', () => { + it('puts the environment setup above the command', () => { + expect( + buildResticScript(makeConfig({ backend: 'local', operation: 'snapshots', passwordMode: 'placeholder' })), + ).toBe("export RESTIC_PASSWORD=''\n\nrestic -r /mnt/backups/restic-repo snapshots"); + }); + + it('returns the bare command when the environment setup is skipped', () => { + expect( + buildResticScript(makeConfig({ backend: 'local', operation: 'snapshots' }), { includeEnvironment: false }), + ).toBe('restic -r /mnt/backups/restic-repo snapshots'); + }); + }); +}); diff --git a/src/tools/restic-command-generator/restic-command-generator.service.ts b/src/tools/restic-command-generator/restic-command-generator.service.ts new file mode 100644 index 00000000..d6f257b2 --- /dev/null +++ b/src/tools/restic-command-generator/restic-command-generator.service.ts @@ -0,0 +1,639 @@ +export type ResticBackend = 'local' | 's3' | 'b2' | 'sftp' | 'rest' | 'rclone' | 'azure' | 'gs' | 'raw'; + +export type ResticOperation = + | 'restore' + | 'dump' + | 'mount' + | 'snapshots' + | 'ls' + | 'find' + | 'diff' + | 'check' + | 'stats' + | 'unlock'; + +export type PasswordMode = 'prompt' | 'placeholder' | 'file' | 'command' | 'none'; +export type CredentialsMode = 'prompt' | 'placeholder' | 'none'; +export type RepositoryMode = 'flag' | 'env'; +export type OverwriteMode = 'default' | 'always' | 'if-changed' | 'if-newer' | 'never'; +export type StatsMode = 'restore-size' | 'files-by-contents' | 'raw-data' | 'blobs-per-file'; +export type DumpArchive = 'none' | 'tar' | 'zip'; + +export interface ResticCommandConfig { + operation: ResticOperation; + + // Repository + backend: ResticBackend; + repositoryMode: RepositoryMode; + localPath: string; + s3Endpoint: string; + s3Bucket: string; + s3Prefix: string; + s3Region: string; + b2Bucket: string; + b2Prefix: string; + sftpUser: string; + sftpHost: string; + sftpPort: string; + sftpPath: string; + restUrl: string; + rcloneRemote: string; + azureContainer: string; + azurePrefix: string; + gsBucket: string; + gsPrefix: string; + rawRepository: string; + + // Secrets + passwordMode: PasswordMode; + passwordFile: string; + passwordCommand: string; + credentialsMode: CredentialsMode; + accountId: string; + + // Snapshot selection + snapshotId: string; + snapshotSubfolder: string; + backrestPlan: string; + backrestInstance: string; + tags: string[]; + host: string; + paths: string[]; + + // restore + target: string; + includes: string[]; + excludes: string[]; + caseInsensitivePatterns: boolean; + dryRun: boolean; + verify: boolean; + sparse: boolean; + deleteExtraneous: boolean; + overwrite: OverwriteMode; + + // dump + dumpPath: string; + dumpArchive: DumpArchive; + dumpOutputFile: string; + + // mount + mountPoint: string; + allowOther: boolean; + + // ls + lsDirectory: string; + lsLong: boolean; + lsRecursive: boolean; + + // find + findPattern: string; + findLong: boolean; + findRestrictToSnapshot: boolean; + + // diff + diffSnapshotId: string; + diffMetadata: boolean; + + // snapshots + snapshotsCompact: boolean; + + // check + checkReadData: boolean; + checkReadDataSubset: string; + checkUnused: boolean; + checkWithCache: boolean; + + // stats + statsMode: StatsMode; + statsAllSnapshots: boolean; + + // unlock + unlockRemoveAll: boolean; + + // Global options + json: boolean; + quiet: boolean; + verbose: boolean; + noCache: boolean; + noLock: boolean; + cacheDir: string; + limitDownload: string; + insecureTls: boolean; + retryLock: string; + extraOptions: string[]; + extraArguments: string; +} + +export const defaultResticCommandConfig: ResticCommandConfig = { + operation: 'restore', + + backend: 's3', + repositoryMode: 'flag', + localPath: '/mnt/backups/restic-repo', + s3Endpoint: 's3.us-west-004.backblazeb2.com', + s3Bucket: 'my-backup-bucket', + s3Prefix: 'backrest', + s3Region: '', + b2Bucket: 'my-backup-bucket', + b2Prefix: 'backrest', + sftpUser: 'backup', + sftpHost: 'nas.lan', + sftpPort: '', + sftpPath: '/srv/restic-repo', + restUrl: 'https://restic.lan:8000/', + rcloneRemote: 'b2-remote:my-backup-bucket/backrest', + azureContainer: 'my-container', + azurePrefix: 'backrest', + gsBucket: 'my-backup-bucket', + gsPrefix: 'backrest', + rawRepository: '', + + passwordMode: 'prompt', + passwordFile: '/root/.restic-password', + passwordCommand: 'pass show restic/repo', + credentialsMode: 'prompt', + accountId: '', + + snapshotId: 'latest', + snapshotSubfolder: '', + backrestPlan: '', + backrestInstance: '', + tags: [], + host: '', + paths: [], + + target: '/mnt/restore', + includes: [], + excludes: [], + caseInsensitivePatterns: false, + dryRun: false, + verify: false, + sparse: false, + deleteExtraneous: false, + overwrite: 'default', + + dumpPath: '/etc/hosts', + dumpArchive: 'none', + dumpOutputFile: '', + + mountPoint: '/mnt/restic', + allowOther: false, + + lsDirectory: '', + lsLong: true, + lsRecursive: false, + + findPattern: '*.conf', + findLong: false, + findRestrictToSnapshot: false, + + diffSnapshotId: '', + diffMetadata: false, + + snapshotsCompact: false, + + checkReadData: false, + checkReadDataSubset: '', + checkUnused: false, + checkWithCache: false, + + statsMode: 'restore-size', + statsAllSnapshots: false, + + unlockRemoveAll: false, + + json: false, + quiet: false, + verbose: false, + noCache: false, + noLock: false, + cacheDir: '', + limitDownload: '', + insecureTls: false, + retryLock: '', + extraOptions: [], + extraArguments: '', +}; + +// Commands that only read from the repository, and so may run with --no-lock. +const READ_ONLY_OPERATIONS: ResticOperation[] = [ + 'restore', + 'dump', + 'mount', + 'snapshots', + 'ls', + 'find', + 'diff', + 'stats', +]; + +// Commands that accept the --host/--tag/--path snapshot filters, mostly used to +// pick which snapshot `latest` resolves to. +const FILTERABLE_OPERATIONS: ResticOperation[] = ['restore', 'dump', 'mount', 'snapshots', 'ls', 'find', 'stats']; + +// Commands that take a snapshot ID as positional argument. +const SNAPSHOT_OPERATIONS: ResticOperation[] = ['restore', 'dump', 'mount', 'ls', 'find', 'diff', 'stats']; + +// Characters a POSIX shell passes through untouched, so simple values stay readable. +const SAFE_ARGUMENT_RE = /^[\w~@%+=:,./-]+$/; + +export function supportsSnapshotFilters(operation: ResticOperation): boolean { + return FILTERABLE_OPERATIONS.includes(operation); +} + +export function supportsSnapshotSelection(operation: ResticOperation): boolean { + return SNAPSHOT_OPERATIONS.includes(operation); +} + +export function supportsNoLock(operation: ResticOperation): boolean { + return READ_ONLY_OPERATIONS.includes(operation); +} + +export function quoteShellArg(value: string): string { + if (value === '') { + return "''"; + } + + if (SAFE_ARGUMENT_RE.test(value)) { + return value; + } + + return `'${value.replace(/'/g, "'\\''")}'`; +} + +function cleanList(values: string[] | undefined): string[] { + return (values ?? []).map((value) => value.trim()).filter((value) => value.length > 0); +} + +function trimSlashes(value: string): string { + return value.trim().replace(/^\/+|\/+$/g, ''); +} + +function joinRepositoryPath(...parts: string[]): string { + return parts + .map(trimSlashes) + .filter((part) => part.length > 0) + .join('/'); +} + +export function buildRepositoryUri(config: ResticCommandConfig): string { + switch (config.backend) { + case 'local': + return config.localPath.trim() || '/path/to/restic-repo'; + case 's3': { + const endpoint = + config.s3Endpoint + .trim() + .replace(/^https?:\/\//, '') + .replace(/\/+$/, '') || 's3.amazonaws.com'; + const path = joinRepositoryPath(config.s3Bucket, config.s3Prefix) || 'my-backup-bucket'; + return `s3:${endpoint}/${path}`; + } + case 'b2': + return `b2:${trimSlashes(config.b2Bucket) || 'my-backup-bucket'}:${trimSlashes(config.b2Prefix) || '/'}`; + case 'sftp': { + const user = config.sftpUser.trim(); + const host = config.sftpHost.trim() || 'backup-host'; + const port = config.sftpPort.trim(); + const path = config.sftpPath.trim() || '/srv/restic-repo'; + const userPrefix = user ? `${user}@` : ''; + + if (port) { + // The URL form is the only one that takes a port; an absolute path needs + // the extra slash (sftp://host:22//srv/repo). + return `sftp://${userPrefix}${host}:${port}/${path.startsWith('/') ? `/${trimSlashes(path)}` : path}`; + } + + return `sftp:${userPrefix}${host}:${path}`; + } + case 'rest': + return `rest:${config.restUrl.trim() || 'https://restic-server:8000/'}`; + case 'rclone': + return `rclone:${config.rcloneRemote.trim() || 'remote:path/to/repo'}`; + case 'azure': + return `azure:${trimSlashes(config.azureContainer) || 'my-container'}:/${trimSlashes(config.azurePrefix)}`; + case 'gs': + return `gs:${trimSlashes(config.gsBucket) || 'my-backup-bucket'}:/${trimSlashes(config.gsPrefix)}`; + case 'raw': + default: + return config.rawRepository.trim() || ''; + } +} + +export interface BackendCredential { + name: string; + value: string; + secret: boolean; +} + +export function getBackendCredentials(config: ResticCommandConfig): BackendCredential[] { + const accountId = config.accountId.trim(); + + switch (config.backend) { + case 's3': { + const credentials: BackendCredential[] = [ + { name: 'AWS_ACCESS_KEY_ID', value: accountId || '', secret: false }, + { name: 'AWS_SECRET_ACCESS_KEY', value: '', secret: true }, + ]; + + if (config.s3Region.trim()) { + credentials.push({ name: 'AWS_DEFAULT_REGION', value: config.s3Region.trim(), secret: false }); + } + + return credentials; + } + case 'b2': + return [ + { name: 'B2_ACCOUNT_ID', value: accountId || '', secret: false }, + { name: 'B2_ACCOUNT_KEY', value: '', secret: true }, + ]; + case 'azure': + return [ + { name: 'AZURE_ACCOUNT_NAME', value: accountId || '', secret: false }, + { name: 'AZURE_ACCOUNT_KEY', value: '', secret: true }, + ]; + case 'gs': + return [ + { name: 'GOOGLE_PROJECT_ID', value: accountId || '', secret: false }, + { name: 'GOOGLE_APPLICATION_CREDENTIALS', value: '/path/to/service-account.json', secret: false }, + ]; + default: + return []; + } +} + +function buildReadSecretLine(name: string): string { + return `read -rsp '${name}: ' ${name} && echo && export ${name}`; +} + +export function buildEnvironmentLines(config: ResticCommandConfig): string[] { + const lines: string[] = []; + + if (config.repositoryMode === 'env') { + lines.push(`export RESTIC_REPOSITORY=${quoteShellArg(buildRepositoryUri(config))}`); + } + + if (config.passwordMode === 'prompt') { + lines.push(buildReadSecretLine('RESTIC_PASSWORD')); + } else if (config.passwordMode === 'placeholder') { + lines.push(`export RESTIC_PASSWORD=${quoteShellArg('')}`); + } + + if (config.credentialsMode !== 'none') { + for (const credential of getBackendCredentials(config)) { + if (credential.secret && config.credentialsMode === 'prompt') { + lines.push(buildReadSecretLine(credential.name)); + } else { + lines.push(`export ${credential.name}=${quoteShellArg(credential.value)}`); + } + } + } + + return lines; +} + +export function buildSnapshotArgument(config: ResticCommandConfig): string { + const snapshotId = config.snapshotId.trim() || 'latest'; + const subfolder = config.snapshotSubfolder.trim(); + + if (!subfolder) { + return snapshotId; + } + + return `${snapshotId}:${subfolder.startsWith('/') ? subfolder : `/${subfolder}`}`; +} + +export function buildTagFilters(config: ResticCommandConfig): string[] { + const backrestTags: string[] = []; + + if (config.backrestPlan.trim()) { + backrestTags.push(`plan:${config.backrestPlan.trim()}`); + } + if (config.backrestInstance.trim()) { + backrestTags.push(`created-by:${config.backrestInstance.trim()}`); + } + + // Tags inside a single --tag are ANDed, repeated --tag flags are ORed, so the + // plan and the instance of the same snapshot must stay in one flag. + const tagFilters = backrestTags.length > 0 ? [backrestTags.join(',')] : []; + + return [...tagFilters, ...cleanList(config.tags)]; +} + +export function buildResticArgumentGroups(config: ResticCommandConfig): string[] { + const groups: string[] = []; + const push = (flag: string, value?: string) => { + groups.push(value === undefined ? flag : `${flag} ${quoteShellArg(value)}`); + }; + const pushPositional = (value: string) => { + groups.push(quoteShellArg(value)); + }; + const pushSnapshotFilters = () => { + if (config.host.trim()) { + push('--host', config.host.trim()); + } + for (const tag of buildTagFilters(config)) { + push('--tag', tag); + } + for (const path of cleanList(config.paths)) { + push('--path', path); + } + }; + + if (config.repositoryMode === 'flag') { + push('-r', buildRepositoryUri(config)); + } + if (config.passwordMode === 'file' && config.passwordFile.trim()) { + push('--password-file', config.passwordFile.trim()); + } + if (config.passwordMode === 'command' && config.passwordCommand.trim()) { + push('--password-command', config.passwordCommand.trim()); + } + if (config.cacheDir.trim()) { + push('--cache-dir', config.cacheDir.trim()); + } + if (config.noCache) { + push('--no-cache'); + } + if (config.noLock && supportsNoLock(config.operation)) { + push('--no-lock'); + } + if (config.limitDownload.trim()) { + push('--limit-download', config.limitDownload.trim()); + } + if (config.retryLock.trim()) { + push('--retry-lock', config.retryLock.trim()); + } + if (config.insecureTls) { + push('--insecure-tls'); + } + for (const option of cleanList(config.extraOptions)) { + push('-o', option); + } + if (config.json) { + push('--json'); + } + if (config.quiet) { + push('--quiet'); + } + if (config.verbose) { + push('--verbose'); + } + + groups.push(config.operation); + + const snapshotArgument = buildSnapshotArgument(config); + const includeFlag = config.caseInsensitivePatterns ? '--iinclude' : '--include'; + const excludeFlag = config.caseInsensitivePatterns ? '--iexclude' : '--exclude'; + + switch (config.operation) { + case 'restore': { + push('--target', config.target.trim() || '/mnt/restore'); + for (const include of cleanList(config.includes)) { + push(includeFlag, include); + } + for (const exclude of cleanList(config.excludes)) { + push(excludeFlag, exclude); + } + if (config.overwrite !== 'default') { + push('--overwrite', config.overwrite); + } + if (config.deleteExtraneous) { + push('--delete'); + } + if (config.sparse) { + push('--sparse'); + } + if (config.verify) { + push('--verify'); + } + if (config.dryRun) { + push('--dry-run'); + } + pushSnapshotFilters(); + pushPositional(snapshotArgument); + break; + } + case 'dump': { + if (config.dumpArchive !== 'none') { + push('--archive', config.dumpArchive); + } + pushSnapshotFilters(); + pushPositional(snapshotArgument); + pushPositional(config.dumpPath.trim() || '/'); + break; + } + case 'mount': { + if (config.allowOther) { + push('--allow-other'); + } + pushSnapshotFilters(); + pushPositional(config.mountPoint.trim() || '/mnt/restic'); + break; + } + case 'snapshots': { + if (config.snapshotsCompact) { + push('--compact'); + } + pushSnapshotFilters(); + break; + } + case 'ls': { + if (config.lsLong) { + push('--long'); + } + if (config.lsRecursive) { + push('--recursive'); + } + pushSnapshotFilters(); + pushPositional(snapshotArgument); + if (config.lsDirectory.trim()) { + pushPositional(config.lsDirectory.trim()); + } + break; + } + case 'find': { + if (config.findLong) { + push('--long'); + } + if (config.caseInsensitivePatterns) { + push('--ignore-case'); + } + if (config.findRestrictToSnapshot) { + push('--snapshot', config.snapshotId.trim() || 'latest'); + } + pushSnapshotFilters(); + pushPositional(config.findPattern.trim() || '*'); + break; + } + case 'diff': { + if (config.diffMetadata) { + push('--metadata'); + } + pushPositional(snapshotArgument); + pushPositional(config.diffSnapshotId.trim() || 'latest'); + break; + } + case 'check': { + if (config.checkReadDataSubset.trim()) { + groups.push(`--read-data-subset=${quoteShellArg(config.checkReadDataSubset.trim())}`); + } else if (config.checkReadData) { + push('--read-data'); + } + if (config.checkUnused) { + push('--check-unused'); + } + if (config.checkWithCache) { + push('--with-cache'); + } + break; + } + case 'stats': { + push('--mode', config.statsMode); + pushSnapshotFilters(); + if (!config.statsAllSnapshots) { + pushPositional(snapshotArgument); + } + break; + } + case 'unlock': { + if (config.unlockRemoveAll) { + push('--remove-all'); + } + break; + } + } + + return groups; +} + +export function buildResticCommand(config: ResticCommandConfig, { multiline = false } = {}): string { + const groups = buildResticArgumentGroups(config); + + if (config.extraArguments.trim()) { + groups.push(config.extraArguments.trim()); + } + + const separator = multiline ? ' \\\n ' : ' '; + let command = `restic${separator}${groups.join(separator)}`; + + if (config.operation === 'dump' && config.dumpOutputFile.trim()) { + command += ` > ${quoteShellArg(config.dumpOutputFile.trim())}`; + } + + return command; +} + +export function buildResticScript( + config: ResticCommandConfig, + { multiline = false, includeEnvironment = true } = {}, +): string { + const environmentLines = includeEnvironment ? buildEnvironmentLines(config) : []; + const command = buildResticCommand(config, { multiline }); + + if (environmentLines.length === 0) { + return command; + } + + return `${environmentLines.join('\n')}\n\n${command}`; +} diff --git a/src/tools/restic-command-generator/restic-command-generator.vue b/src/tools/restic-command-generator/restic-command-generator.vue new file mode 100644 index 00000000..0d49fa67 --- /dev/null +++ b/src/tools/restic-command-generator/restic-command-generator.vue @@ -0,0 +1,911 @@ + + + + +