System Operations Guide

https://yahyatoubali.github.io/televault
Admin
Provides comprehensive technical documentation covering system commands, engine architecture,...
Tokens:11,107
Snippets:145
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### TeleVault Installation and Commands

Source: https://yahyatoubali.github.io/televault?q=

Install TeleVault via pipx and demonstrates common commands for setup, upload, download, listing, and streaming files.

```bash
# Install
pipx install televault

# Login — will prompt for API credentials from https://my.telegram.org
tvt login

# Setup storage channel (interactive)
tvt setup

# Upload
tvt push photo.jpg
tvt push --recursive /data/documents

# Download
tvt pull photo.jpg
tvt pull photo.jpg -o /tmp/photo.jpg

# List
tvt ls
tvt ls --json | jq '.[].name'

# Stream to stdout
tvt cat config.yaml | grep api_key
cat secret.txt | tvt push - --name secret.txt
```

--------------------------------

### Install and Serve TeleVault with WebDAV

Source: https://yahyatoubali.github.io/televault/virtualization?q=

Install the WebDAV extra for TeleVault and start the server. The server defaults to listening on all interfaces and port 8080. Custom host and port can be specified, and read-only mode is available.

```bash
pipx install televault[webdav]

# Default: http://0.0.0.0:8080
tvt serve

# Custom host/port
tvt serve --host 192.168.1.100 --port 9090

# Read-only
tvt serve --read-only

```

--------------------------------

### Install and Basic Usage

Source: https://yahyatoubali.github.io/televault?q=

Install TeleVault using pipx and perform initial login and file upload.

```bash
$ pipx install televault
$ tvt login
$ tvt push secret.tar.gz
```

--------------------------------

### Install WebDAV server support for TeleVault

Source: https://yahyatoubali.github.io/televault/virtualization

Install the Televault package with WebDAV server capabilities using pipx.

```bash
pipx install televault[webdav]
```

--------------------------------

### Install FUSE dependencies on macOS

Source: https://yahyatoubali.github.io/televault/virtualization

Instructions to install macFUSE on macOS.

```bash
# macOS
# Install macFUSE from https://macfuse.io/
```

--------------------------------

### Start TeleVault WebDAV server on custom host and port

Source: https://yahyatoubali.github.io/televault/virtualization

Start the TeleVault WebDAV server on a custom IP address and port.

```bash
# Custom host/port
tvt serve --host 192.168.1.100 --port 9090
```

--------------------------------

### Install FUSE support for TeleVault

Source: https://yahyatoubali.github.io/televault/virtualization

Install the Televault package with FUSE capabilities using pipx.

```bash
pipx install televault[fuse]
```

--------------------------------

### Install FUSE dependencies on Linux

Source: https://yahyatoubali.github.io/televault/virtualization

Install the necessary FUSE packages on a Linux system.

```bash
# Linux
sudo apt install fuse libfuse2
```

--------------------------------

### Start TeleVault WebDAV server on default host and port

Source: https://yahyatoubali.github.io/televault/virtualization

Start the TeleVault WebDAV server using the 'tvt serve' command. It defaults to http://0.0.0.0:8080.

```bash
# Default: http://0.0.0.0:8080
tvt serve
```

--------------------------------

### Upload from stdin

Source: https://yahyatoubali.github.io/televault/commands?q=

This example demonstrates how to upload a file from standard input to Televault, piping the content of 'secret.txt' and naming it 'secret.txt'.

```bash
# Upload from stdin
cat secret.txt | tvt push - --name secret.txt
```

--------------------------------

### Start TeleVault WebDAV server in read-only mode

Source: https://yahyatoubali.github.io/televault/virtualization

Start the TeleVault WebDAV server with read-only access enabled.

```bash
# Read-only
tvt serve --read-only
```

--------------------------------

### Stream to stdout

Source: https://yahyatoubali.github.io/televault/commands?q=

This example shows how to stream the content of a file from Televault to standard output, allowing it to be processed by other command-line tools like 'grep'.

```bash
# Stream to stdout
tvt cat config.yaml | grep api_key
```

--------------------------------

### JSON output with jq

Source: https://yahyatoubali.github.io/televault/commands?q=

These examples illustrate how to use the '--json' flag with Televault commands and pipe the output to 'jq' for structured data parsing and extraction.

```bash
# JSON output with jq
tvt ls --json | jq '.[].name'
```

```bash
tvt stat --json | jq '.total_files'
```

```bash
tvt info photo.jpg --json | jq '.size'
```

```bash
tvt find report --json | jq 'length'
```

--------------------------------

### Install and Mount TeleVault with FUSE

Source: https://yahyatoubali.github.io/televault/virtualization?q=

Install the FUSE extra for TeleVault and mount your vault. Use `--read-only` for read-only access or specify cache options for read-write mounts.

```bash
pipx install televault[fuse]

# Read-only mount
tvt mount ~/vault --read-only

# Read-write with custom cache
tvt mount ~/vault --cache-size 500 --cache-dir /tmp/tvcache

```

--------------------------------

### FUSE Mount Requirements

Source: https://yahyatoubali.github.io/televault/virtualization?q=

Install FUSE and its dependencies. For macOS, install macFUSE from the official website.

```bash
# Linux
sudo apt install fuse libfuse2

# macOS
# Install macFUSE from https://macfuse.io/

```

--------------------------------

### JSON Output Processing with jq

Source: https://yahyatoubali.github.io/televault/commands

Examples of using the `--json` flag with Televault commands and piping the output to `jq` for structured data parsing and manipulation.

```bash
tvt ls --json | jq '.[].name'
```

```bash
tvt stat --json | jq '.total_files'
```

```bash
tvt info photo.jpg --json | jq '.size'
```

```bash
tvt find report --json | jq 'length'
```

--------------------------------

### Resumable Download Progress File

Source: https://yahyatoubali.github.io/televault/security

Example JSON structure for a progress file used in resumable downloads, tracking completed chunks and file integrity.

```json
{
  "file_id": "abc123",
  "completed_chunks": [0, 1, 2],
  "total_chunks": 5,
  "checksum": "a1b2c3d4"
}

```

--------------------------------

### Launch Televault TUI

Source: https://yahyatoubali.github.io/televault/commands

Starts the interactive terminal user interface for Televault. This feature is currently in beta.

```bash
tvt tui
```

--------------------------------

### Configure TeleVault Performance Settings

Source: https://yahyatoubali.github.io/televault/hardware?q=

Tune upload and download parallelism, chunk size, and retry settings by modifying the TeleVault configuration file. Ensure chunk_size is in bytes.

```json
{
  "parallel_uploads": 8,
  "parallel_downloads": 10,
  "chunk_size": 268435456,
  "max_retries": 3,
  "retry_delay": 1.0
}

```

--------------------------------

### Mount TeleVault with custom cache settings

Source: https://yahyatoubali.github.io/televault/virtualization

Mount your TeleVault as a read-write filesystem with a specified cache size and directory.

```bash
# Read-write with custom cache
tvt mount ~/vault --cache-size 500 --cache-dir /tmp/tvcache
```

--------------------------------

### scrypt Key Derivation

Source: https://yahyatoubali.github.io/televault/security

Demonstrates key derivation using scrypt with specified parameters for password-based encryption.

```python
key = scrypt(
    password=user_password,
    salt=random_16_bytes,
    N=131072,      # 2^17
    r=8,
    p=1,
    dklen=32       # 256-bit key
)

```

--------------------------------

### Mount TeleVault as read-only filesystem

Source: https://yahyatoubali.github.io/televault/virtualization

Mount your TeleVault as a read-only filesystem using the 'tvt mount' command.

```bash
# Read-only mount
tvt mount ~/vault --read-only
```

--------------------------------

### Create Backup Schedule

Source: https://yahyatoubali.github.io/televault/commands

Use this command to create a new backup schedule. You can specify a directory, a name, and options for daily, weekly, or monthly intervals, as well as incremental backups.

```bash
tvt schedule create <dir> --name <n>
```

```bash
tvt schedule create --interval daily
```

```bash
tvt schedule create --incremental
```

--------------------------------

### Manage Backup Schedules

Source: https://yahyatoubali.github.io/televault/commands

Commands to list, run, delete, and manage systemd timers for backup schedules.

```bash
tvt schedule list
```

```bash
tvt schedule run <name>
```

```bash
tvt schedule delete <name>
```

```bash
tvt schedule install <name>
```

```bash
tvt schedule uninstall <name>
```

```bash
tvt schedule show-systemd <name>
```

--------------------------------

### Upload from Stdin

Source: https://yahyatoubali.github.io/televault/commands

Pipes the content of a file from standard input to the `tvt push` command for uploading. The `--` indicates that the source is stdin.

```bash
cat secret.txt | tvt push - --name secret.txt
```

--------------------------------

### FUSE Mount How It Works - Conceptual Flow

Source: https://yahyatoubali.github.io/televault/virtualization

Illustrates the on-demand chunk streaming process when an application reads from a FUSE-mounted TeleVault.

```text
Application reads bytes 0-4096 from file.jpg
    │
    ▼
FUSE getattr → cached metadata (30s TTL)
    │
    ▼
FUSE open → prefetch first 3 chunks into LRU cache
    │
    ▼
FUSE read → fetch_range(0, 4096)
    │
    ▼
ChunkCache.fetch_chunk(0) → download from Telegram
    │
    ▼
Decrypt → Decompress → Return bytes 0-4096
```

--------------------------------

### scrypt Key Derivation

Source: https://yahyatoubali.github.io/televault/security?q=

Demonstrates the scrypt function used for deriving a 256-bit key from a user password and a random salt. The parameters N, r, and p are chosen to balance security and performance.

```python
key = scrypt(
    password=user_password,
    salt=random_16_bytes,
    N=131072,      # 2^17
    r=8,
    p=1,
    dklen=32       # 256-bit key
)
```

--------------------------------

### Configure Televault Performance Settings

Source: https://yahyatoubali.github.io/televault/hardware

Tune upload and download parallelism, chunk size, and retry parameters by modifying the Televault configuration file. The default chunk size is 256 MB, and it can be reduced for lower memory usage.

```json
{
  "parallel_uploads": 8,
  "parallel_downloads": 10,
  "chunk_size": 268435456,
  "max_retries": 3,
  "retry_delay": 1.0
}
```

--------------------------------

### Download Decryption Pipeline

Source: https://yahyatoubali.github.io/televault/engine?q=

Details the steps involved in downloading and decrypting a file, including hash verification, decryption, decompression, and final file integrity checks.

```text
Download chunk by message_id
      │
      ▼
   Verify BLAKE3 hash (ChunkInfo.hash)
      │
      ▼
   AES-256-GCM Decryption
   ── extract 28-byte header (salt + nonce)
   ── scrypt(password, salt) → key
   ── decrypt and verify GCM tag
      │
      ▼
   zstd Decompression
      │
      ▼
   Verify original_hash (BLAKE3)
   ── catches wrong-password decryption that passes GCM
      │
      ▼
   Write chunk at offset via ChunkWriter
      │
      ▼
   Verify file-level BLAKE3 hash (FileMetadata.hash)


```

--------------------------------

### Upload Encryption Pipeline

Source: https://yahyatoubali.github.io/televault/engine?q=

Illustrates the sequence of operations during file upload, from chunking and hashing to compression, encryption, and final upload to Telegram.

```text
Original File
      │
      ▼
   Chunker (256 MB slices)
      │
      ▼
   BLAKE3 hash (original_hash)
      │
      ▼
   zstd Compression (level 3)
   ── skipped for incompressible extensions
      │
      ▼
   AES-256-GCM Encryption
   ── scrypt(password, salt) → 32-byte key
   ── 16-byte salt + 12-byte nonce = 28-byte header
   ── ciphertext + 16-byte auth tag
   ── overhead: 44 bytes per chunk
      │
      ▼
   BLAKE3 hash of encrypted data (ChunkInfo.hash)
      │
      ▼
   Upload as Telegram file message (reply to metadata)


```

--------------------------------

### Enable Low-Resource Mode

Source: https://yahyatoubali.github.io/televault/hardware?q=

Use the --low-resource flag to enable low-resource mode for TeleVault commands. This reduces memory usage by adjusting chunk size and parallelism.

```bash
tvt push large_file.iso --low-resource
tvt pull large_file.iso --low-resource --resume

```

--------------------------------

### Encrypt-then-Upload Pipeline Diagram

Source: https://yahyatoubali.github.io/televault/security

Visual representation of the data processing pipeline from original file to Telegram upload.

```text
┌──────────┐    ┌──────────┐    ┌──────────────┐    ┌────────────┐    ┌──────────┐
│ Original  │───▶│  Chunk   │───▶│  BLAKE3 Hash │───▶│  zstd      │───▶│  AES-256 │
│  File     │    │  (256MB) │    │  (original)  │    │  Compress  │    │  GCM     │
└──────────┘    └──────────┘    └──────────────┘    └────────────┘    └──────────┘
                                                                              │
                                                                              ▼
┌──────────┐    ┌──────────┐    ┌──────────────┐    ┌────────────┐    ┌──────────┐
│ Telegram  │◀───│ Upload   │◀───│ BLAKE3 Hash  │◀───│ Ciphertext │◀───│ Encrypted│
│ Channel   │    │ File Msg │    │ (encrypted)  │    │ + Tag      │    │ Chunk    │
└──────────┘    └──────────┘    └──────────────┘    └────────────┘    └──────────┘

```

--------------------------------

### Enable Low-Resource Mode for Televault Commands

Source: https://yahyatoubali.github.io/televault/hardware

Use the `--low-resource` flag to enable low-resource mode for Televault push and pull operations. This mode adjusts chunk size and parallelism for systems with limited RAM.

```bash
tvt push large_file.iso --low-resource
tvt pull large_file.iso --low-resource --resume
```

--------------------------------

### Scrypt Key Derivation Parameters

Source: https://yahyatoubali.github.io/televault/engine?q=

Specifies the parameters for the scrypt key derivation function, including cost factors (N, r, p) and output size. This is used for generating encryption keys from passwords.

```pseudocode
scrypt(password, salt):
  N = 2^17 (131072)
  r = 8
  p = 1
  output = 32 bytes (256-bit AES key)


```

--------------------------------

### Resumable Download Progress File

Source: https://yahyatoubali.github.io/televault/security?q=

Shows the structure of a progress file used for resumable downloads. It includes file identification, completed chunk indices, total chunks, and a checksum for integrity.

```json
{
  "file_id": "abc123",
  "completed_chunks": [0, 1, 2],
  "total_chunks": 5,
  "checksum": "a1b2c3d4"
}
```

--------------------------------

### Decryption Verification Flow

Source: https://yahyatoubali.github.io/televault/security

Illustrates the verification process after decryption to detect incorrect passwords that might otherwise produce valid-looking ciphertext.

```text
decrypt → decompress → verify original_hash → FAIL → wrong password

```

--------------------------------

### TeleVault Upload Progress Indicator

Source: https://yahyatoubali.github.io/televault/hardware?q=

Observe the CLI's network speed tracking using Exponential Moving Average (EMA) smoothing, which updates every chunk with a specified smoothing factor to minimize jitter.

```text
⬆️ Uploading photo.jpg (3/8 chunks)  45.2 MB/s  ████████████░░░░░░░░ 65%

```

--------------------------------

### Watch Directory for Changes

Source: https://yahyatoubali.github.io/televault/commands

Monitor a directory for file changes. You can set the polling interval and specify exclude patterns for files that should not be watched.

```bash
tvt watch --path <dir>
```

```bash
tvt watch --interval 10
```

```bash
tvt watch --exclude "*.tmp"
```

--------------------------------

### Global CLI Flags

Source: https://yahyatoubali.github.io/televault/commands

Common flags that can be used with most Televault commands to control logging level, display version, or show help information.

```bash
tvt -v, --verbose
```

```bash
tvt --debug
```

```bash
tvt --version
```

```bash
tvt --help
```

--------------------------------

### Stream to Stdout

Source: https://yahyatoubali.github.io/televault/commands

Streams the content of a file to standard output using `tvt cat`, which can then be piped to other commands like `grep` for processing.

```bash
tvt cat config.yaml | grep api_key
```

--------------------------------

### Resume Interrupted TeleVault Operations

Source: https://yahyatoubali.github.io/televault/hardware?q=

Utilize the --resume flag to continue interrupted uploads or downloads. TeleVault preserves partial data and uses CRC32 checksums for progress file integrity.

```bash
# Resume interrupted upload
tvt push large_file.iso --resume

# Resume interrupted download
tvt pull large_file.iso --resume

```

--------------------------------

### FileMetadata Structure

Source: https://yahyatoubali.github.io/televault/engine?q=

Contains detailed information about a stored file, including its ID, name, size, encryption status, and a list of its chunks with associated message IDs and hashes.

```json
{
  "id": "abc123def456",
  "name": "photo.jpg",
  "size": 5242880,
  "hash": "a1b2c3d4...64 chars BLAKE3",
  "chunks": [
    {
      "index": 0,
      "message_id": 43,
      "size": 10485780,
      "hash": "e5f6a7b8...post-processing",
      "original_hash": "c9d0e1f2...pre-processing"
    }
  ],
  "encrypted": true,
  "compressed": true,
  "created_at": 1700000000.0
}

```

--------------------------------

### Televault Transfer Speed Indicator

Source: https://yahyatoubali.github.io/televault/hardware

The Televault CLI displays upload progress and transfer speed using Exponential Moving Average (EMA) smoothing. Speed is updated per chunk with a smoothing factor to minimize jitter.

```text
⬆️ Uploading photo.jpg (3/8 chunks)  45.2 MB/s  ████████████░░░░░░░░ 65%
```

--------------------------------

### Resume Interrupted Televault Operations

Source: https://yahyatoubali.github.io/televault/hardware

Televault supports resuming interrupted uploads and downloads. Partial data is preserved even if the progress file becomes corrupted, and operations will restart from the beginning.

```bash
# Resume interrupted upload
tvt push large_file.iso --resume

# Resume interrupted download
tvt pull large_file.iso --resume
```

--------------------------------

### AES-256-GCM Chunk Structure

Source: https://yahyatoubali.github.io/televault/security?q=

Details the on-disk structure of an encrypted chunk, including the salt, nonce, ciphertext, and authentication tag.

```plaintext
[16-byte salt][12-byte nonce][ciphertext...][16-byte auth tag]
```

--------------------------------

### AES-256-GCM Chunk Structure

Source: https://yahyatoubali.github.io/televault/security

Defines the structure of an encrypted chunk on disk, including salt, nonce, ciphertext, and authentication tag.

```text
[16-byte salt][12-byte nonce][ciphertext...][16-byte auth tag]

```

--------------------------------

### Decryption Integrity Check Flow

Source: https://yahyatoubali.github.io/televault/security?q=

Illustrates the integrity verification process after decryption, ensuring that the original data can be recovered by verifying the pre-processing hash. This catches cases where a wrong password might produce seemingly valid but corrupted data.

```plaintext
decrypt → decompress → verify original_hash → FAIL → wrong password
```

--------------------------------

### VaultIndex Storage Model

Source: https://yahyatoubali.github.io/televault/engine?q=

Represents the main index for stored files, tracking file hashes and their corresponding Telegram message IDs. The version increments on each save.

```json
{
  "version": 7,
  "files": { "abc123def456": 42, "def789ghi012": 87 },
  "updated_at": 1700000100.0
}

```

--------------------------------

### Compressing Large Index Messages

Source: https://yahyatoubali.github.io/televault/engine?q=

This snippet shows how TeleVault compresses large index messages that exceed Telegram's 4096-character limit using zlib and base64 encoding. Decompression is handled transparently.

```python
if len(json_text) > 4096:
    compressed = zlib.compress(json_text, level=9)
    encoded = base64.b64encode(compressed)
    message = f"__TV1__{encoded}"
```
Tokens:
Raw