توثيق CLI الخاص بـ LockBox

البدء السريع

ضع LockBox.Cli.exe في مجلد مضمن في PATH، أو قم باستدعاؤه عبر المسار الكامل. ووسم --cli مقبول للتوافق ولكنه غير مطلوب في النسخة الخاصة بسطر الأوامر فقط.

.\LockBox.Cli.exe --help
.\LockBox.Cli.exe device-id
.\LockBox.Cli.exe algorithms
.\LockBox.Cli.exe keygen --count 3

الحد الأدنى لتدفق إنشاء وفتح:

$env:LBX_MASTER = "use-a-long-master-password"
$env:LBX_L1 = "layer-1-key"

.\LockBox.Cli.exe create `
  --source "D:\Data" `
  --output "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-128-GCM=LBX_L1

.\LockBox.Cli.exe open `
  --container "E:\Backups\data.lbx" `
  --output "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1

تستخدم لينكس نفس الأوامر مع مسارات مائلة وثنائي بدون اللاحقة .exe:

chmod +x ./LockBox.Cli
./LockBox.Cli --help
./LockBox.Cli device-id
./LockBox.Cli create \
  --source "/srv/data" \
  --output "/backup/data.lbx" \
  --master-env LBX_MASTER \
  --layer-env AES-128-GCM=LBX_L1

تثبيت واجهة CLI والتحقق منها

فك ضغط ملف ZIP المناسب للنظام والمعالج. يتضمن البرنامج .NET. قارن قيمة التجزئة مع SHA256SUMS.txt. ضع CLI في المسار المطلق الموضح أدناه، وافحص المساعدة والترخيص باستخدام حساب النسخ الاحتياطي.

يحتاج Linux أيضًا إلى مكتبات التوزيعة الأصلية، ومنها ICU وOpenSSL؛ ولا يوفرها .NET المضمّن. في Windows يجب أن تسمح سياسة التنفيذ الفعلية بتشغيل سكربتات PowerShell.

.NET / Linux · PowerShell / ExecutionPolicy

Expand-Archive -LiteralPath '.\LockBox-Cli-win-x64.zip' -DestinationPath 'C:\Tools\LockBox'
& 'C:\Tools\LockBox\LockBox.Cli.exe' --help
& 'C:\Tools\LockBox\LockBox.Cli.exe' license
Get-FileHash -LiteralPath '.\LockBox-Cli-win-x64.zip' -Algorithm SHA256

uname -m
unzip LockBox-Cli-linux-x64.zip -d ./lockbox-cli
chmod +x ./lockbox-cli/LockBox.Cli
./lockbox-cli/LockBox.Cli --help
./lockbox-cli/LockBox.Cli license
sha256sum LockBox-Cli-linux-x64.zip

SHA256SUMS.txt

Windows x64   -> LockBox-Cli-win-x64.zip
Windows x86   -> LockBox-Cli-win-x86.zip
Windows ARM64 -> LockBox-Cli-win-arm64.zip
Linux x86_64  -> LockBox-Cli-linux-x64.zip
Linux aarch64 -> LockBox-Cli-linux-arm64.zip
Linux armv7l  -> LockBox-Cli-linux-arm.zip

المجلدات والمسارات والمساحة

عدّل المسارات لتناسب بيئتك. يجب ألا يكون مجلد المصدر فارغًا، ويجب حفظ الحاوية خارجه. استخدام اسم الإخراج نفسه يستبدل الحاوية السابقة وأجزاءها. وفّر مساحة مؤقتة بجوار الحاوية ونسخة من المصدر للمهام المجدولة. وحدات الحجم أساسها 1024؛ والحشو يضيف بايتات ولا يحدد الحجم النهائي.

C:\Tools\LockBox\LockBox.Cli.exe     /opt/lockbox/LockBox.Cli
C:\LockBox\secrets\master.txt       /srv/lockbox/secrets/master.txt
C:\LockBox\secrets\layer1.txt       /srv/lockbox/secrets/layer1.txt
C:\LockBox\backup.ps1               /srv/lockbox/backup.sh
D:\Data\report.csv                 /srv/data/report.csv
E:\Backups\20260910-020000\data.lbx  /backup/20260910-020000/data.lbx
D:\Restore\Data\report.csv         /restore/data/report.csv

& 'C:\Tools\LockBox\LockBox.Cli.exe' create --source 'D:\Data' --output 'E:\Backups\data.lbx' --master-file 'C:\LockBox\secrets\master.txt' --layer-file 'AES-128-GCM=C:\LockBox\secrets\layer1.txt'

/opt/lockbox/LockBox.Cli create --source /srv/data --output /backup/data.lbx --master-file /srv/lockbox/secrets/master.txt --layer-file AES-128-GCM=/srv/lockbox/secrets/layer1.txt

إعداد ملفات الأسرار

أنشئ الأسرار مرة واحدة، واحتفظ بنسخة محمية وقيّد الوصول إلى الملفات. ترفض الأمثلة استبدال المفاتيح الموجودة. تحتفظ ملفات UTF-8 بالمسافات وتحذف فواصل الأسطر النهائية. احتفظ بالمفاتيح الأصلية للنسخ القديمة.

$ErrorActionPreference = 'Stop'
$cli = 'C:\Tools\LockBox\LockBox.Cli.exe'
$secretDir = 'C:\LockBox\secrets'
New-Item -ItemType Directory -Force -Path $secretDir | Out-Null
$files = @('master.txt', 'layer1.txt')
foreach ($name in $files) {
    if (Test-Path -LiteralPath (Join-Path $secretDir $name)) {
        throw "Secret already exists: $name"
    }
}
foreach ($name in $files) {
    $key = & $cli keygen --count 1
    if ($LASTEXITCODE -ne 0) { throw 'Key generation failed' }
    [IO.File]::WriteAllText((Join-Path $secretDir $name), [string]$key, [Text.UTF8Encoding]::new($false))
}

set -eu
umask 077
mkdir -p /srv/lockbox/secrets
test ! -e /srv/lockbox/secrets/master.txt
test ! -e /srv/lockbox/secrets/layer1.txt
set -C
/opt/lockbox/LockBox.Cli keygen --count 1 > /srv/lockbox/secrets/master.txt
/opt/lockbox/LockBox.Cli keygen --count 1 > /srv/lockbox/secrets/layer1.txt

التفعيل وحالة الترخيص

مفتاح الترخيص مرتبط بمعرّف الجهاز الذي يتم طباعته بواسطة نفس نسخة CLI. إذا تم نسخ الترخيص إلى جهاز كمبيوتر آخر، فإن LockBox يرفضه ويعود إلى النسخة المجانية.

يقوم ويندوز بفحص مواقع بيانات تطبيق LockBox الموجودة. تخزن لينكس التفعيل في $XDG_CONFIG_HOME/lockbox/.lockbox.license، ثم ~/.config/lockbox/.lockbox.license، مع ~/.lockbox/.lockbox.license كنسخة احتياطية.

.\LockBox.Cli.exe device-id

.\LockBox.Cli.exe license

التفعيل من ملف الترخيص

.\LockBox.Cli.exe activate --license-file "C:\Licenses\lockbox-license.txt"

التفعيل من متغير بيئة

$env:LBX_LICENSE = "LBX-LIC-..."
.\LockBox.Cli.exe activate --license-env LBX_LICENSE

التفعيل المباشر

التفعيل المباشر يعمل، ولكنه قد يتسرب من خلال سجل الأوامر أو سجلات العمليات.

.\LockBox.Cli.exe activate --license "LBX-LIC-..."

تفعيل لينكس

export LBX_LICENSE="LBX-LIC-..."
./LockBox.Cli activate --license-env LBX_LICENSE
./LockBox.Cli license

معالجة الأسرار

يُفضل استخدام متغيرات البيئة أو الملفات. الأسرار المضمنة مفيدة للاختبار فقط. يجب الحفاظ على كلمات المرور الرئيسية ومفاتيح الطبقات: بدونها لا يمكن فتح الحاوية.

الأسرار المستندة إلى الملفات

Set-Content -Path ".\master.txt" -Value "master-password" -Encoding UTF8
Set-Content -Path ".\layer1.txt" -Value "layer-key-1" -Encoding UTF8

.\LockBox.Cli.exe create `
  -s "D:\Data" `
  -o "E:\Backups\data.lbx" `
  --master-file ".\master.txt" `
  --layer-file AES-128-GCM=.\layer1.txt

الخوارزميات وتوليد المفاتيح

استخدم algorithms لرؤية جميع الملفات الشخصية المدعومة والإصدارات الدنيا. استخدم keygen لمفاتيح الطبقة.

.\LockBox.Cli.exe algorithms
.\LockBox.Cli.exe keygen
.\LockBox.Cli.exe keygen --count 9
.\LockBox.Cli.exe generate-keys -n 20

الأسماء المستعارة للأوامر المدعومة:

algorithms
list-algorithms
profiles

keygen
generate-key
generate-keys

إنشاء الحاويات

create يقوم بتغليف مجلد المصدر، ويطبق ضغطًا واختياريًا إضافة حشو، ويشفّر الحمولات عبر طبقة أو أكثر، ويكتب حاوية .lbx.

الخيارات المطلوبة

• --source أو -s: مجلد المصدر.
• --output أو -o: مسار .lbx الناتج.
• --master، --master-env، أو --master-file.
• طبقة واحدة على الأقل: --layer، --layer-env، أو --layer-file.

حاوية AES الحد الأدنى

.\LockBox.Cli.exe create `
  -s "D:\Data" `
  -o "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-128-GCM=LBX_L1

الحاوية المضغوطة

.\LockBox.Cli.exe create `
  --source "D:\Exports" `
  --output "E:\Backups\exports.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --compress

حشو التشفير

.\LockBox.Cli.exe create `
  -s "D:\Contracts" `
  -o "E:\Backups\contracts.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --padding 2GB

تقسيم الحاوية إلى أجزاء

.\LockBox.Cli.exe create `
  -s "D:\Media" `
  -o "E:\Backups\media.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --split 700MB

الجزء الأول يحتفظ بـ .lbx. الأجزاء الإضافية تستخدم .lbx1، .lbx2، وهكذا. احتفظ بجميع الأجزاء في نفس المجلد.

مثال للحد الأقصى بتسع طبقات

$env:LBX_MASTER = "use-a-long-master-password"
$env:LBX_L1 = "layer-1-key"
$env:LBX_L2 = "layer-2-key"
$env:LBX_L3 = "layer-3-key"
$env:LBX_L4 = "layer-4-key"
$env:LBX_L5 = "layer-5-key"
$env:LBX_L6 = "layer-6-key"
$env:LBX_L7 = "layer-7-key"
$env:LBX_L8 = "layer-8-key"
$env:LBX_L9 = "layer-9-key"

.\LockBox.Cli.exe create `
  --source "D:\Data" `
  --output "E:\Backups\data-max.lbx" `
  --master-env LBX_MASTER `
  --compress `
  --padding 2GB `
  --split 700MB `
  --layer-env AES-256-GCM=LBX_L1 `
  --layer-env CHACHA20-POLY1305=LBX_L2 `
  --layer-env AES-256-CCM=LBX_L3 `
  --layer-env SERPENT-256-CTR-HMACSHA512=LBX_L4 `
  --layer-env TWOFISH-256-CTR-HMACSHA512=LBX_L5 `
  --layer-env CAMELLIA-256-CTR-HMACSHA512=LBX_L6 `
  --layer-env ARIA-256-CTR-HMACSHA512=LBX_L7 `
  --layer-env AES-256-CBC-HMACSHA512=LBX_L8 `
  --layer-env AES-192-OFB-HMACSHA384=LBX_L9

صياغة بديلة للخوارزمية/المفتاح

.\LockBox.Cli.exe create `
  -s "D:\Data" `
  -o "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --algorithm AES-128-GCM --key-env LBX_L1 `
  --algorithm AES-128-CTR-HMACSHA256 --key-env LBX_L2

حذف المصدر بعد الإنشاء اليدوي الناجح

.\LockBox.Cli.exe create `
  -s "D:\TempToEncrypt" `
  -o "E:\Backups\temp.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --delete-source

--delete-source يحذف مجلد المصدر فقط بعد إنشاء الحاوية بنجاح. المجدول لديه خيار مختلف: --delete-source-contents.

كلمة مرور تدمير الحاوية

يمكن لإصدار Max إضافة كلمة مرور تدمير منفصلة إلى الحاوية. إذا تم إدخال هذه الكلمة لاحقًا ككلمة المرور الرئيسية، يقوم LockBox على الفور بالكتابة فوق الحاوية دون تأكيد. هذا مخصص لسيناريوهات الضغط والإكراه. احتفظ بها منفصلة عن كلمة المرور الرئيسية الحقيقية.

يتحقق الأمر من مساحة القرص الحرة، ويشفّر بيانات الحاوية الأصلية بسر عشوائي جديد وAES-256-GCM في ملف مؤقت، ويقوم بتطبيع النتيجة للحجم الأصلي بالضبط، ويستبدل الملف الأصلي، وينسى السر العشوائي. بالنسبة للحاويات المقسمة، يتم استبدال كل جزء .lbx, .lbx1, .lbx2 في نفس المجلد مع الحفاظ على أحجام الأجزاء الأصلية.

إنشاء بكلمة مرور التدمير

$env:LBX_MASTER = "real-master-password"
$env:LBX_L1 = "layer-key-1"
$env:LBX_DESTROY = "pressure-password"

.\LockBox.Cli.exe create `
  --source "D:\Data" `
  --output "E:\Backups\data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --destruction-password-env LBX_DESTROY

تشغيل التدمير بدون مفاتيح الطبقة

.\LockBox.Cli.exe open `
  --container "E:\Backups\data.lbx" `
  --output "D:\Restore" `
  --master-env LBX_DESTROY

تشغيل على لينكس

export LBX_DESTROY="pressure-password"
./LockBox.Cli open \
  --container "/backup/data.lbx" \
  --output "/restore" \
  --master-env LBX_DESTROY

بعد التدمير الناجح، لم تعد الحاوية ملف LockBox صالح. يُرجع CLI رمز الخروج 0 لأن إجراء التدمير المطلوب اكتمل بنجاح.

فتح الحاويات

open يقوم باستخراج الحاوية إلى مجلد الإخراج. للاستخراج العادي، يجب تمرير مفاتيح الطبقة بالترتيب نفسه المستخدم أثناء الإنشاء. في سير عمل كلمة مرور التدمير، يُطلب فقط مسار الحاوية، مسار الإخراج، وكلمة مرور التدمير ككلمة المرور الرئيسية.

فتح حاوية بطبقة واحدة

.\LockBox.Cli.exe open `
  --container "E:\Backups\data.lbx" `
  --output "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1

فتح حاوية مقسمة

.\LockBox.Cli.exe open `
  -c "E:\Backups\data.lbx" `
  -o "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1

فتح حاوية متعددة الطبقات

.\LockBox.Cli.exe open `
  -c "E:\Backups\data-max.lbx" `
  -o "D:\Restore" `
  --master-env LBX_MASTER `
  --key-env LBX_L1 `
  --key-env LBX_L2 `
  --key-env LBX_L3 `
  --key-env LBX_L4 `
  --key-env LBX_L5 `
  --key-env LBX_L6 `
  --key-env LBX_L7 `
  --key-env LBX_L8 `
  --key-env LBX_L9

الأسماء المستعارة

open
decrypt
extract

التحقق من النسخة باستعادتها

أنشئ ملف report.csv صغيرًا للاختبار. استخرج إلى مجلد جديد؛ وسيحتفظ داخله باسم مجلد المصدر. اجمع جميع الأجزاء وقارن الملفات بالمصدر دون تغييره. يحتاج الاستخراج مساحة مؤقتة قابلة للكتابة بجوار الحاوية. احمِ الملفات المستعادة غير المشفرة أيضًا.

$ErrorActionPreference = 'Stop'
$cli = 'C:\Tools\LockBox\LockBox.Cli.exe'
$container = 'E:\Backups\data.lbx'
$restore = Join-Path 'D:\RestoreChecks' ([guid]::NewGuid().ToString('N'))
& $cli open --container $container --output $restore --master-file 'C:\LockBox\secrets\master.txt' --key-file 'C:\LockBox\secrets\layer1.txt'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
$original = (Get-FileHash -LiteralPath 'D:\Data\report.csv' -Algorithm SHA256).Hash
$restored = (Get-FileHash -LiteralPath (Join-Path $restore 'Data\report.csv') -Algorithm SHA256).Hash
if ($original -ne $restored) { throw 'SHA256 mismatch' }
Write-Output $restore

set -eu
umask 077
mkdir -p /restore
restore=$(mktemp -d /restore/check-XXXXXX)
/opt/lockbox/LockBox.Cli open --container /backup/data.lbx --output "$restore" --master-file /srv/lockbox/secrets/master.txt --key-file /srv/lockbox/secrets/layer1.txt
cmp /srv/data/report.csv "$restore/data/report.csv"
sha256sum /srv/data/report.csv "$restore/data/report.csv"

الجدول

أوامر الجدول متاحة في الإصدار ماكس. تقوم بتخزين جميع بيانات المهام في ملف مشفر .lbxjobs، بما في ذلك مسار المصدر، مسار المخرجات، كلمات المرور، كلمة مرور الحذف، مفاتيح الطبقات، الضغط، الحشو، التقسيم، وإعداد حذف محتويات المصدر.

تعمل المهام المجدولة فقط أثناء تشغيل LockBox.Cli.exe schedule run. استخدم جدولة مهام ويندوز، نظام systemd على لينكس، cron، غلاف الخدمة، أو جلسة وحدة تحكم طويلة التشغيل إذا كنت بحاجة إلى بدء العامل تلقائيًا بعد إعادة التشغيل.

قيم التكرار

once
30m
hourly
2h
3h
6h
9h
12h
18h
daily
2d
3d
5d
weekly
2w
monthly
2mo
3mo
6mo
9mo
yearly

إضافة مهمة نسخ احتياطي مشفر يوميًا

$env:LBX_JOBS_PASSWORD = "jobs-file-password"
$env:LBX_MASTER = "master-password"
$env:LBX_L1 = "layer-key-1"
$env:LBX_DESTROY = "pressure-password"

.\LockBox.Cli.exe schedule add `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --name "Nightly data backup" `
  --frequency daily `
  --start ((Get-Date).AddDays(1).ToString("o")) `
  --source "D:\Data" `
  --output "E:\Backups\nightly-data.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --destruction-password-env LBX_DESTROY `
  --compress

إضافة مهمة تحذف محتويات المجلد المصدر بعد النجاح

.\LockBox.Cli.exe schedule add `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --name "Encrypt outgoing folder" `
  --frequency 30m `
  --start ((Get-Date).AddDays(1).ToString("o")) `
  --source "D:\Outgoing" `
  --output "E:\Backups\outgoing.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --delete-source-contents

إضافة أرشيف شهري مع الحشو وتقسيم الأجزاء

.\LockBox.Cli.exe schedule add `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --name "Monthly legal archive" `
  --frequency monthly `
  --start ((Get-Date).AddDays(1).ToString("o")) `
  --source "D:\Legal" `
  --output "E:\Archives\legal-monthly.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --compress `
  --padding 4GB `
  --split 2GB

قائمة المهام المحفوظة

.\LockBox.Cli.exe schedule list `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD

تشغيل عامل الجدول

.\LockBox.Cli.exe schedule run `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --state "E:\Backups\jobs.status.json" `
  --poll-seconds 30

تشغيل المهام المستحقة مرة واحدة والخروج

.\LockBox.Cli.exe schedule run-once `
  --tasks "E:\Backups\jobs.lbxjobs" `
  --password-env LBX_JOBS_PASSWORD `
  --state "E:\Backups\jobs.status.json"

عرض حالة التشغيل الأخيرة

.\LockBox.Cli.exe schedule status --state "E:\Backups\jobs.status.json"

علامات الحالة هي [OK]، [RUNNING]، و[FAILED]. تتضمن المهمة الفاشلة السبب وتخبر المستخدم بالاتصال بالدعم إذا تكرر المشكلة.

سكريبتات JSON

استخدم --script عندما تحتوي سير العمل على عدة خطوات. يدعم مشغل السكريبتات create، open، keygen، algorithms، device-id، license، وactivate.

إنشاء وفتح في سكريبت واحد

{
  "stopOnError": true,
  "commands": [
    {
      "command": "create",
      "source": "D:\\Data",
      "output": "E:\\Backups\\data.lbx",
      "masterPasswordEnv": "LBX_MASTER",
      "destructionPasswordEnv": "LBX_DESTROY",
      "compression": true,
      "padding": "512MB",
      "split": "700MB",
      "layers": [
        { "algorithm": "AES-256-GCM", "keyEnv": "LBX_L1" },
        { "algorithm": "CHACHA20-POLY1305", "keyEnv": "LBX_L2" }
      ]
    },
    {
      "command": "open",
      "container": "E:\\Backups\\data.lbx",
      "output": "D:\\Restore",
      "masterPasswordEnv": "LBX_MASTER",
      "keyEnvs": [ "LBX_L1", "LBX_L2" ]
    }
  ]
}

.\LockBox.Cli.exe --script ".\backup.lockbox.json"

الاستمرار بعد خطوة فاشلة

{
  "stopOnError": false,
  "commands": [
    { "command": "license" },
    { "command": "algorithms" },
    {
      "command": "create",
      "source": "D:\\BuildOutput",
      "output": "E:\\Artifacts\\build.lbx",
      "masterPasswordEnv": "LBX_MASTER",
      "layers": [
        { "algorithm": "AES-128-GCM", "keyEnv": "LBX_L1" }
      ]
    }
  ]
}

التنشيط من السكريبت

{
  "commands": [
    {
      "command": "activate",
      "licenseKeyFile": "C:\\Licenses\\lockbox-license.txt"
    },
    { "command": "license" }
  ]
}

حقول JSON وقواعد التنفيذ

يربط الجدول حقول create ومصفوفات مفاتيح open بخيارات CLI. تبدأ المسارات النسبية من مجلد عمل العملية، لا من ملف JSON؛ ولا تُستبدل المتغيرات والتواريخ داخل النصوص. استخدم مصدر سر واحدًا لكل حقل. يقرأ open بالترتيب keys ثم keyEnvs ثم keyFiles. يفضّل stopOnError: true؛ فقد يخفي نجاح لاحق خطأ سابقًا عند false. لا تدعم سكربتات JSON أوامر المجدول.

{
  "stopOnError": true,
  "commands": [
    {
      "command": "create",
      "source": "/srv/data",
      "output": "/backup/data.lbx",
      "masterPasswordFile": "/srv/lockbox/secrets/master.txt",
      "layers": [
        { "algorithm": "AES-128-GCM", "keyFile": "/srv/lockbox/secrets/layer1.txt" }
      ]
    },
    {
      "command": "open",
      "container": "/backup/data.lbx",
      "output": "/restore/check",
      "masterPasswordFile": "/srv/lockbox/secrets/master.txt",
      "keyFiles": ["/srv/lockbox/secrets/layer1.txt"]
    }
  ]
}

/opt/lockbox/LockBox.Cli --quiet script /srv/lockbox/backup.lockbox.json

وصفات الأتمتة

نسخ احتياطي لمخزن قاعدة بيانات مشفر

$stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$dump = "D:\DbDumps\$stamp"
New-Item -ItemType Directory -Path $dump | Out-Null

Copy-Item "D:\DatabaseExports\*" $dump -Recurse

.\LockBox.Cli.exe create `
  -s $dump `
  -o "E:\Backups\db-$stamp.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --compress `
  --padding 512MB

حماية مخرجات CI

.\LockBox.Cli.exe create `
  --source "$env:BUILD_ARTIFACTSTAGINGDIRECTORY" `
  --output "$env:AGENT_TEMPDIRECTORY\protected-artifacts.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-128-GCM=LBX_L1

نقل آمن للشركاء

.\LockBox.Cli.exe create `
  -s "D:\PartnerPackage" `
  -o "E:\Transfer\partner-package.lbx" `
  --master-env LBX_MASTER `
  --layer-env AES-256-GCM=LBX_L1 `
  --layer-env CHACHA20-POLY1305=LBX_L2 `
  --compress `
  --split 1GB

أرشيف طويل الأمد

.\LockBox.Cli.exe create `
  -s "D:\Records\2026" `
  -o "E:\ColdStorage\records-2026.lbx" `
  --master-file "C:\Secrets\records-master.txt" `
  --layer-file AES-256-GCM=C:\Secrets\records-layer1.txt `
  --layer-file SERPENT-256-CTR-HMACSHA512=C:\Secrets\records-layer2.txt `
  --compress `
  --padding 8GB `
  --split 4GB

مثال على ملف دفعي

@echo off
set LBX_MASTER=master-password
set LBX_L1=layer-key-1

LockBox.Cli.exe create ^
  --source "D:\Data" ^
  --output "E:\Backups\data.lbx" ^
  --master-env LBX_MASTER ^
  --layer-env AES-128-GCM=LBX_L1

if errorlevel 1 exit /b %errorlevel%
echo OK

Windows: نسخ عدة مجلدات

احفظ السكربت في المسار المحدد. ينشئ حاوية باسم فريد وسجلًا لكل مصدر، ويتوقف عند الخطأ مع الحفاظ على رمز خروج CLI. يعمل AES-128-GCM في Free؛ ويتطلب الضغط والتقسيم Pro أو Max.

C:\LockBox\backup.ps1

param(
    [string[]]$Source = @('D:\Data'),
    [string]$Destination = 'E:\Backups'
)
$ErrorActionPreference = 'Stop'
$cli = 'C:\Tools\LockBox\LockBox.Cli.exe'
$secretDir = 'C:\LockBox\secrets'
try {
    foreach ($folder in $Source) {
        $sourcePath = (Resolve-Path -LiteralPath $folder).Path
        $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMdd-HHmmss-fff')
        $runId = [guid]::NewGuid().ToString('N')
        $runDir = Join-Path $Destination "$stamp-$runId"
        New-Item -ItemType Directory -Path $runDir | Out-Null
        $container = Join-Path $runDir 'data.lbx'
        $log = Join-Path $runDir 'create.log'
        $cliArgs = @(
            '--quiet', 'create', '--source', $sourcePath, '--output', $container,
            '--master-file', (Join-Path $secretDir 'master.txt'),
            '--layer-file', ('AES-128-GCM=' + (Join-Path $secretDir 'layer1.txt'))
        )
        $ErrorActionPreference = 'Continue'
        & $cli @cliArgs > $log 2>&1
        $result = $LASTEXITCODE
        $ErrorActionPreference = 'Stop'
        if ($result -ne 0) {
            Get-Content -LiteralPath $log
            exit $result
        }
        if (-not (Test-Path -LiteralPath $container -PathType Leaf)) {
            throw "Container missing: $container"
        }
        Write-Output $container
    }
    exit 0
} catch {
    Write-Error $_ -ErrorAction Continue
    exit 1
}

& 'C:\LockBox\backup.ps1' -Source 'D:\Data', 'D:\Reports' -Destination 'E:\Backups'
# 0 = success; 1 = runtime error; 2 = usage error; 3 = edition restriction
$LASTEXITCODE

Linux: نسخ احتياطي دون إشراف

احفظ سكربت Bash بنهايات أسطر LF. جهّز CLI وملفات الأسرار في المسارات المحددة، ومرّر مجلدات المصدر كوسائط. يحصل كل تشغيل على مجلد مستقل. تترك الأخطاء سجلًا وتعيد رمزًا غير صفري؛ وتبقى ملفات المصدر محفوظة.

/srv/lockbox/backup.sh

#!/bin/bash
set -eu
umask 077
cli=/opt/lockbox/LockBox.Cli
secret_dir=/srv/lockbox/secrets
backup_root=/backup
mkdir -p "$backup_root"
if [ "$#" -eq 0 ]; then
    set -- /srv/data
fi
for source in "$@"; do
    run_dir=$(mktemp -d "$backup_root/$(date -u +%Y%m%d-%H%M%S)-XXXXXX")
    container="$run_dir/data.lbx"
    log="$run_dir/create.log"
    "$cli" --quiet create \
        --source "$source" \
        --output "$container" \
        --master-file "$secret_dir/master.txt" \
        --layer-file "AES-128-GCM=$secret_dir/layer1.txt" > "$log" 2>&1 || {
        result=$?
        cat "$log" >&2
        exit "$result"
    }
    test -s "$container"
    printf '%s\n' "$container"
done

/bin/bash /srv/lockbox/backup.sh /srv/data /srv/reports

الجدولة عبر نظام التشغيل

تشغّل هذه المهام السكربتات السابقة؛ ولا يتطلب هذا الاستخدام للأمر create إصدار Max. يعمل تسجيل Windows الموضح أثناء تسجيل دخول المستخدم فقط؛ واضبط التشغيل دون تسجيل دخول في جدولة المهام عند الحاجة. أضف سطر cron إلى crontab لحساب النسخ بعد التأكد من تثبيت flock. يعمل المثالان عند 02:00 بالتوقيت المحلي ويمنعان تداخل التشغيلات المجدولة. افحص الأذونات واختبر يدويًا أولًا.

Windows

$action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-NoProfile -NonInteractive -File "C:\LockBox\backup.ps1"' -WorkingDirectory 'C:\LockBox'
$trigger = New-ScheduledTaskTrigger -Daily -At '02:00'
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -MultipleInstances IgnoreNew -ExecutionTimeLimit ([TimeSpan]::Zero)
$principal = New-ScheduledTaskPrincipal -UserId ([Security.Principal.WindowsIdentity]::GetCurrent().Name) -LogonType Interactive
Register-ScheduledTask -TaskName 'LockBox backup' -Action $action -Trigger $trigger -Settings $settings -Principal $principal
Start-ScheduledTask -TaskName 'LockBox backup'
Get-ScheduledTaskInfo -TaskName 'LockBox backup'

New-ScheduledTaskSettingsSet · New-ScheduledTaskPrincipal

Linux: cron

crontab -e

0 2 * * * /usr/bin/flock -n /srv/lockbox/backup.lock /bin/bash /srv/lockbox/backup.sh >> /srv/lockbox/cron.log 2>&1

crontab(5)

Max: تشغيل المجدول وإدارته

أنشئ حساب خدمة lockbox بالأذونات اللازمة، وفعّل Max لهذا الحساب، وجهّز ملف كلمة مرور UTF-8 مستقلًا باسم jobs.txt. الأمر add يضيف ولا يحدّث؛ استخدمه مرة لكل مهمة. شغّل عملية واحدة لكل ملف مهام وأعد تشغيلها بعد التعديلات. لا يستعيد JSON الحالة سجل التنفيذ: تُتجاوز التكرارات الفائتة، وقد تعمل مهمة once المتأخرة مجددًا. استخدم create للتشغيل الدوري بواسطة النظام بدل تكرار run-once. يعيد المجدول استخدام اسم الإخراج المحدد.

/opt/lockbox/LockBox.Cli schedule add \
  --tasks /srv/lockbox/jobs.lbxjobs \
  --password-file /srv/lockbox/secrets/jobs.txt \
  --name nightly-data --frequency daily \
  --start "$(date -d 'tomorrow 02:00' --iso-8601=seconds)" \
  --source /srv/data --output /backup/nightly-data.lbx \
  --master-file /srv/lockbox/secrets/master.txt \
  --layer-file AES-128-GCM=/srv/lockbox/secrets/layer1.txt

/opt/lockbox/LockBox.Cli schedule list --tasks /srv/lockbox/jobs.lbxjobs --password-file /srv/lockbox/secrets/jobs.txt

/etc/systemd/system/lockbox-scheduler.service

[Unit]
Description=LockBox scheduler
After=local-fs.target
RequiresMountsFor=/srv/data /srv/lockbox /backup

[Service]
Type=simple
User=lockbox
WorkingDirectory=/srv/lockbox
UMask=0077
ExecStart=/opt/lockbox/LockBox.Cli schedule run --tasks /srv/lockbox/jobs.lbxjobs --password-file /srv/lockbox/secrets/jobs.txt --state /srv/lockbox/jobs.status.json --poll-seconds 30
Restart=on-failure
RestartSec=10
KillSignal=SIGINT
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now lockbox-scheduler.service
systemctl status lockbox-scheduler.service
journalctl -u lockbox-scheduler.service -n 50 --no-pager
/opt/lockbox/LockBox.Cli schedule status --state /srv/lockbox/jobs.status.json

systemd.service

مرجع الأوامر

خيارات الإنشاء

خيارات الفتح

خيارات الجدولة

استخدم --language أو --lang لاختيار لغة وحدة التحكم، و--quiet لإخفاء رسائل التقدم المعتادة؛ وتظل الأخطاء تُرسل إلى مجرى الخطأ القياسي. يطلب Ctrl+C الإلغاء ويعيد الرمز 1. يعني الرمز 2 أن صياغة الأمر غير صحيحة؛ ويعني الرمز 3 أن ميزة إنشاء غير متاحة في الإصدار الحالي. يشمل الرمز 0 أيضًا تفعيل كلمة مرور الإتلاف عمدًا، لذا لا يثبت وحده استخراج الملفات. تحقق من الإخراج المتوقع قبل تنفيذ خطوات الأتمتة اللاحقة.

رموز الخروج ومراقبة النسخ

قد يعيد schedule run-once صفرًا رغم فشل المهام، ويعيد schedule status صفرًا عند غياب الحالة أيضًا. افحص savedAt وlastSuccessAt وlastError؛ فقد تعني [OK] مجرد Ready. يفترض المراقب نسخًا يومية وفحصًا كل 30 ثانية ونجاحًا خلال 26 ساعة. عدّل الحدود وفق جدولك. حالات JSON أرقام؛ ويخفي --quiet المخرجات المعتادة للأمرين create/open عند النجاح.

$ErrorActionPreference = 'Stop'
try {
    $status = Get-Content -LiteralPath 'E:\Backups\jobs.status.json' -Raw | ConvertFrom-Json
    if (@($status.tasks).Count -eq 0) { throw 'No tasks in status file' }
    if ([DateTimeOffset]$status.savedAt -lt [DateTimeOffset]::Now.AddMinutes(-2)) {
        throw 'Worker status is stale'
    }
    foreach ($task in $status.tasks) {
        if ($task.state -eq 3 -or $task.lastError) { throw "Task failed: $($task.name)" }
        if (-not $task.lastSuccessAt -or [DateTimeOffset]$task.lastSuccessAt -lt [DateTimeOffset]::Now.AddHours(-26)) {
            throw "No recent successful backup: $($task.name)"
        }
    }
    exit 0
} catch {
    Write-Error $_ -ErrorAction Continue
    exit 1
}

0 -> Ready
1 -> Running
2 -> Completed
3 -> Failed

استكشاف الأخطاء وإصلاحها