# CommandSection

title: PACKAGE SOURCE
content:
The <I>pyversions</I> command is typically provided by the <I>python-minimal</I> package on Debian and Ubuntu distributions.


title: ROLE IN PYTHON ECOSYSTEM
content:
It acts as a simple interface to query the system's awareness of installed Python versions, which are often configured using the <I>update-alternatives</I> system to manage the default <I>python</I> command.


title: HISTORY
content:
The <I>pyversions</I> command emerged as part of Debian's system for managing multiple Python interpreters, particularly with the transition from Python 2 to Python 3. It became especially relevant when both major versions were commonly installed, and system utilities or user scripts might depend on a specific <I>python</I> executable. It helps identify which versions are available and how the system's <I>python</I> symlink might be configured via <I>update-alternatives</I>. While its direct usage might decrease as Python 2 becomes obsolete, it remains a useful diagnostic tool on Debian-based systems for understanding Python environment configurations.


title: PARAMETERS
content:
<b>-H, --header</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assume input files have a header row. This is often the default for CSV/TSV.<br><br><b>-N, --skip-header</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assume input files have no header row.<br><br><b>-d <i>DELIMITER</i>, --delimiter <i>DELIMITER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the input column delimiter (e.g., <i>,</i> for CSV, <i>\t</i> for TSV, <i>|</i> for pipe-separated).<br><br><b>-O <i>DELIMITER</i>, --output-delimiter <i>DELIMITER</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output column delimiter. Defaults to the input delimiter if not specified.<br><br><b>-t, --tsv</b><br>&nbsp;&nbsp;&nbsp;&nbsp;A shortcut to set the input delimiter to tab (<i>\t</i>).<br><br><b>-c <i>COLUMNS</i>, --columns <i>COLUMNS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Manually specify column names (e.g., <i>id,name,value</i>) when no header is present or to override detected headers.<br><br><b>--as-json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treat input files as JSON. <b>q</b> can parse JSON arrays of objects.<br><br><b>--from-file <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the SQL query from the specified file instead of directly from the command line.<br><br><b>--low-memory</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable low memory mode, useful for processing very large files by reducing in-memory caching.<br><br><b>--no-header-output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the header row in the output, useful when piping results to other tools.<br><br>


title: DESCRIPTION
content:
The <b>q</b> command is a powerful command-line tool that allows users to execute SQL-like queries directly on various text files, treating them as if they were tables in a relational database. Developed by Harel Ben-Attia, it provides an intuitive way to filter, transform, and analyze data from CSV, TSV, JSON, Apache logs, and other delimited or structured text formats, without requiring data to be loaded into an actual database system.<br><br>By leveraging a subset of the SQL-92 standard, <b>q</b> enables complex data manipulation operations such as <i>SELECT</i> with various clauses (<i>WHERE</i>, <i>GROUP BY</i>, <i>ORDER BY</i>, <i>LIMIT</i>), <i>JOIN</i> operations across multiple files, and the use of aggregate functions like <i>COUNT</i>, <i>SUM</i>, <i>AVG</i>, <i>MIN</i>, and <i>MAX</i>. It intelligently handles common scenarios like header detection, various delimiters, and can infer column types. Its ability to process data directly from standard input and output results to standard output makes it highly composable within typical Unix pipelines, integrating seamlessly with other command-line utilities.<br><br>This tool is particularly useful for system administrators, data analysts, and developers who frequently work with log files, configuration files, or other forms of structured text data. It offers a quick and efficient method for ad-hoc data analysis, reporting, and transformation tasks, effectively bridging the gap between simple text processing utilities and full-fledged database management systems. While not a complete database, its 'text as a database' paradigm simplifies many common data wrangling challenges.


title: CAVEATS
content:
<b>q</b> is not a full-fledged relational database management system. It lacks features such as persistent storage, transactions, indexing for query optimization, and complex data types. While efficient for many tasks, performance on extremely large datasets with very complex <i>JOIN</i> operations might not match optimized database engines. It requires Python and the <b>q</b> Python package to be installed on the system.


title: INPUT AND OUTPUT FLEXIBILITY
content:
<b>q</b> excels in its versatility with input and output. It can process data from standard input (stdin) or multiple specified files, automatically detecting common delimiters like comma, tab, or space. For output, it typically writes to standard output (stdout), allowing seamless integration into shell pipelines for further processing with tools like <b>awk</b>, <b>sed</b>, or <b>jq</b>.


title: SQL-92 COMPLIANCE
content:
While not a complete SQL implementation, <b>q</b> supports a significant subset of the SQL-92 standard. This includes <i>SELECT</i> statements with clauses like <i>FROM</i>, <i>WHERE</i>, <i>GROUP BY</i>, <i>ORDER BY</i>, <i>LIMIT</i>, <i>HAVING</i>, <i>UNION ALL</i>, and <i>DISTINCT</i>. It also supports aggregate functions (e.g., <i>COUNT</i>, <i>SUM</i>, <i>AVG</i>), and cross-file <i>JOIN</i> operations, enabling powerful data correlation across different text sources.


title: HISTORY
content:
The <b>q</b> command was created by Harel Ben-Attia, with its first public release appearing around 2012. It quickly gained popularity within the Unix command-line community for its innovative approach to querying text files using familiar SQL syntax. The project is actively maintained on GitHub, with ongoing development and improvements to its SQL compliance and performance.


title: PARAMETERS
content:
<b>--evaluate, -e</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Evaluate the given expression and exit.</i> (This is the default if an expression is provided.)<br><br><b>--interactive, -i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Run <b><code>qalc</code></b> in interactive mode, allowing continuous input of expressions.</i><br><br><b>--convert, -c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Convert the result of the expression to specified units or currencies (e.g., <code>10m -> ft</code>).</i><br><br><b>--terse, -t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Produce terse output, omitting the expression prefix and other decorative elements.</i><br><br><b>--precision, -p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set the numeric precision for calculations.</i><br><br><b>--set, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set internal variables or options (e.g., <code>base=hex</code> or <code>auto_post_conversion=off</code>).</i><br><br><b>--list-functions, -a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>List all available mathematical functions supported by <b><code>qalc</code></b>.</i><br><br><b>--list-units, -u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>List all supported units and currencies.</i><br><br><b>--base, -B</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set the default output number base (e.g., <code>binary</code>, <code>octal</code>, <code>hexadecimal</code>).</i><br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Display a help message and exit.</i><br><br><b>--version, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show version information and exit.</i><br><br>


title: DESCRIPTION
content:
<b><code>qalc</code></b> is the command-line interface for <i><I>Qalculate!</I></i>, a powerful and versatile desktop calculator. It provides advanced mathematical functionality directly in your terminal, supporting everything from basic arithmetic to complex symbolic calculations, unit conversions, currency exchange, and statistical analysis. Users can evaluate expressions non-interactively or enter an interactive mode for continuous calculations. Its extensive built-in function library, support for variables, and ability to handle arbitrary precision numbers make it an indispensable tool for engineers, scientists, and anyone needing robust calculation capabilities beyond simple <b><code>bc</code></b> or <b><code>expr</code></b>.


title: CAVEATS
content:
<b><code>qalc</code></b> relies on the <i><I>Qalculate!</I></i> library, which must be installed on the system. While extremely powerful, its comprehensive features can sometimes present a steeper learning curve compared to simpler calculators. Unit and currency exchange rates require occasional updates from online sources to remain accurate.


title: INTERACTIVE MODE
content:
When run with no arguments or the <b><code>-i</code></b> option, <b><code>qalc</code></b> enters an interactive shell where users can type expressions continuously, define variables, create custom functions, and manage the calculation environment. This mode is ideal for complex, multi-step computations.


title: UNIT AND CURRENCY CONVERSION
content:
One of <b><code>qalc</code></b>'s most powerful features is its robust unit and currency conversion capabilities. Expressions like <code>10 USD to EUR</code> or <code>50 miles / hour to km/s</code> are easily handled. It can automatically fetch up-to-date currency exchange rates and supports a vast library of physical units, making it invaluable for scientific and engineering calculations.


title: SYMBOLIC CALCULATIONS
content:
Beyond numerical computation, <b><code>qalc</code></b> can perform symbolic operations such as simplifying algebraic expressions, differentiating functions (e.g., <code>diff(x^2 + 2x, x)</code>), and solving equations. This makes it a versatile tool for tasks that traditionally require more specialized mathematical software.


title: HISTORY
content:
<b><code>qalc</code></b> is part of the <i><I>Qalculate!</I></i> project, an open-source, multi-platform desktop calculator developed by <i><I>Niklas Knutsson</I></i>. The project began around 2001, aiming to provide a powerful and versatile calculator with a user-friendly interface. The command-line <b><code>qalc</code></b> utility was developed alongside the GUI, offering the core calculation engine's capabilities to script and terminal environments, maintaining feature parity with the underlying library and ensuring consistent functionality.


title: PARAMETERS
content:
<b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message detailing the command's usage, available options, and arguments.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows version information for the specific <b>qc</b> implementation.<br><br><b><b>-o</b> <i>&lt;dir&gt;</i>, <b>--output-dir</b>=<i>&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the directory where output files, reports, or processed results should be generated. This is a common option for tools that produce new data.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, providing more detailed progress information, warnings, or debugging messages during execution.<br><br><b><b>--config</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an external configuration file to load settings for the <b>qc</b> operation, allowing for flexible and reusable parameter sets.<br><br><b><b>--report-type</b> <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the format of the generated report, such as <i>HTML</i>, <i>JSON</i>, <i>TXT</i>, or other specific formats. Only applicable if the <b>qc</b> command generates reports.<br><br><b>[<i>FILES...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files to be processed by the <b>qc</b> command. These could be raw data files, results from previous steps, or configuration inputs.<br><br>


title: DESCRIPTION
content:
The <b>qc</b> command is <i>not</i> a standard, universally installed Linux utility. Unlike core system commands like <b>ls</b> or <b>grep</b>, <b>qc</b>'s presence and functionality are highly context-dependent and typically arise from specific software installations or custom user configurations.<br><br>Common contexts where a command named <b>qc</b> might be found include:<br><i>1. Bioinformatics:</i> Often used as a shorthand or wrapper script for <b>Quality Control</b> (QC) procedures on biological data, especially high-throughput sequencing data. It might automate tasks performed by tools like <b>FastQC</b> or <b>MultiQC</b>, or perform custom data integrity checks.<br><i>2. Computational Chemistry/Physics:</i> Within specialized software suites (e.g., Q-Chem, Gaussian, VASP), <b>qc</b> might refer to commands related to <b>Quantum Chemistry</b> calculations, such as job submission, post-processing of output files, or analysis of computational results.<br><i>3. Custom Scripts/Aliases:</i> Many users or system administrators create an alias or a shell script named <b>qc</b> to encapsulate a series of frequently used quality checks, complex command pipelines, or specific data processing workflows tailored to their projects.<br><br>Due to its non-standard nature, the exact behavior, available options, and expected inputs/outputs of <b>qc</b> are entirely dependent on its specific implementation in the environment where it is encountered. Users should consult local documentation or script contents to understand its purpose.


title: CAVEATS
content:
The <b>qc</b> command is <i>not</i> a standard Linux utility and is <i>not</i> part of the core GNU or Unix toolset. Its presence and functionality are entirely dependent on specific software installations (e.g., bioinformatics tools, quantum chemistry packages) or custom user-defined scripts/aliases. Therefore, any analysis of <b>qc</b> must be context-specific. Users should consult the documentation pertinent to the software package or script where <b>qc</b> is used, as its behavior can vary widely.


title: TYPICAL USE CASES
content:
When present, <b>qc</b> is commonly used for:<br>1. <i>Preliminary Data Assessment:</i> Quickly checking the quality and integrity of raw experimental data.<br>2. <i>Automated Reporting:</i> Generating summary reports that flag potential issues in data quality or computational output.<br>3. <i>Job Management:</i> In computational science, it might submit, monitor, or retrieve results from quantum chemistry calculations.<br>4. <i>Workflow Integration:</i> Serving as a modular component within larger data processing or computational pipelines.


title: CUSTOM IMPLEMENTATIONS
content:
Many users create their own <b>qc</b> alias or shell script. This allows them to quickly execute frequently used quality checks or complex command sequences with a simple, memorable command, tailoring it precisely to their specific project requirements or lab standards. These custom implementations are often found in a user's <i>PATH</i> via directories like <i>~/bin</i> or as part of project-specific environment setups.


title: HISTORY
content:
The 'history' of a command named <b>qc</b> is highly fragmented and specific to the domains in which it appears, rather than representing a unified lineage within general-purpose Linux. In bioinformatics, a <b>qc</b> utility typically emerged as a convenient wrapper or script to automate quality control workflows for high-throughput sequencing data, often to simplify complex command-line arguments or integrate multiple steps. Similarly, in computational chemistry, <b>qc</b> might be part of a larger software suite's user interface, developed to streamline the submission and analysis of quantum chemistry calculations. Its evolution is thus tied to the development and user convenience within these specialized scientific software fields, not a general operating system utility.


title: SYNOPSIS
content:
<i>qcp</i> [<i>OPTIONS</i>] <i>SOURCE</i>... <i>DESTINATION</i><br><i>or</i><br><i>qcp</i> <i>SOURCE_FILE</i> <i>DESTINATION_FILE</i><br><i>or</i><br><i>qcp</i> <i>SOURCE_DIR</i> <i>DESTINATION_DIR</i>


title: PARAMETERS
content:
<b><i>SOURCE</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more source files or directories to copy. For multiple sources, <i>DESTINATION</i> must be a directory.<br><br><b><i>DESTINATION</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target directory or new name for the copied file. If multiple sources are provided, it must be an existing directory.<br><br><b><i>-r</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively copy directories and their contents. This is a common default for many <i>qcp</i> implementations.<br><br><b><i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing files as they are copied. Useful for monitoring progress.<br><br><b><i>-f</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force overwrite of existing destination files without prompting. Use with caution.<br><br><b><i>-i</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompt before overwriting an existing destination file. Provides an interactive safeguard.<br><br><b><i>-p</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserve attributes such as file mode, ownership, and timestamps of the original files.<br><br>


title: DESCRIPTION
content:
<i>qcp</i> is <b>not</b> a standard Linux command or utility distributed with major distributions. It typically refers to a custom script or a shell alias created by users or system administrators to simplify common file and directory copying operations. Often, it acts as a wrapper around the more powerful and standard <i>cp</i> command, or sometimes <i>rsync</i>, pre-configuring frequently used options like recursive copying (for directories), verbose output, or preserving file attributes. The primary goal of <i>qcp</i> is to reduce typing and streamline repetitive copy tasks, making it a 'quick copy' utility tailored to specific workflows. Its exact behavior, options, and capabilities are entirely dependent on how it has been implemented on a given system.


title: CAVEATS
content:
<i>qcp</i> is <b>not</b> a standard Linux command. Its existence and functionality are entirely dependent on whether a user or system administrator has created a custom script or shell alias named <i>qcp</i>. Therefore, it may not be available on all systems, and its behavior (including available options) will vary widely based on its specific implementation (e.g., whether it wraps <i>cp</i>, <i>rsync</i>, or something else entirely). Users should consult local documentation or the script's source code if <i>qcp</i> is encountered.


title: COMMON IMPLEMENTATIONS
content:
A <i>qcp</i> script is most commonly implemented as a simple shell script (e.g., Bash) or an alias.<br><b>Example Alias:</b> <code>alias qcp='cp -rv'</code> (for recursive and verbose copy)<br><b>Example Script:</b> A more complex script might parse arguments, offer different modes, or integrate with other tools like <i>rsync</i> for more robust error handling or progress indication.


title: PURPOSE
content:
The primary purpose of <i>qcp</i> is often to abstract away the complexities of <i>cp</i>'s various options for common tasks, providing a simpler, memorable command that performs a frequently needed operation with minimal typing.


title: HISTORY
content:
The concept of a <i>qcp</i> command typically arises from users or system administrators seeking to streamline their daily workflows. It's not part of any official GNU or standard Linux project history. Instead, <i>qcp</i> scripts are often created out of necessity, as a personal productivity enhancement, or as a convenient wrapper in specific IT environments to enforce certain copying behaviors or defaults (e.g., always recursive, always verbose). Its "development" is therefore decentralized and specific to individual system setups.


title: SYNOPSIS
content:
<b>qdbus</b> [<i>--system</i> | <i>--session</i>] [<i>--literal</i>] [<i>--monitor</i> | <i>--help</i> | <i>--version</i>]<br><b>qdbus</b> [<i>--system</i> | <i>--session</i>] [<i>--literal</i>] <i>service</i> [<i>path</i> [<i>interface</i> [<i>method</i> [<i>arguments...</i>]]]]


title: PARAMETERS
content:
<b><i>--system</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the system-wide D-Bus bus instead of the default session bus.<br><br><b><i>--session</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly uses the user's session D-Bus bus (this is the default behavior).<br><br><b><i>--literal</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs arguments literally, without converting backslash sequences or other special characters.<br><br><b><i>--monitor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Monitors and displays all D-Bus signals and method calls flowing through the bus.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a short help message and exits.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information for <i><b>qdbus</b></i> and exits.<br><br><b><i>service</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The well-known D-Bus service name (e.g., <i>org.kde.konsole</i>). If only this is provided, <i><b>qdbus</b></i> lists objects for the service.<br><br><b><i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The object path within the D-Bus service (e.g., <i>/Konsole/MainApplication</i>). If provided with <i>service</i>, lists interfaces for the object.<br><br><b><i>interface</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The D-Bus interface name (e.g., <i>org.kde.konsole.Konsole</i>). If provided with <i>service</i> and <i>path</i>, lists methods, signals, and properties for the interface.<br><br><b><i>method</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the method to invoke on the specified interface. Must be combined with <i>service</i>, <i>path</i>, and <i>interface</i>.<br><br><b><i>arguments...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more arguments to pass to the invoked <i>method</i>. Arguments are space-separated.<br><br>


title: DESCRIPTION
content:
<i><b>qdbus</b></i> is a command-line utility provided by the Qt framework to interact with the D-Bus message bus. It allows users to list available D-Bus services, inspect objects and interfaces exposed by these services, and invoke methods on them. It simplifies debugging and scripting interactions with D-Bus applications, especially those built with Qt. <i><b>qdbus</b></i> can operate on both the system and session D-Bus buses, making it a versatile tool for various system-level and user-level D-Bus communications. It's particularly useful for exploring the D-Bus interface of applications when documentation is scarce, or for quick command-line automation. Its hierarchical approach to introspection, starting from services, then objects, and finally interfaces, makes it intuitive to navigate complex D-Bus architectures.


title: CAVEATS
content:
While powerful, <i><b>qdbus</b></i> is part of the Qt framework and its introspection capabilities might sometimes differ slightly from other D-Bus tools. It's primarily designed for interactive exploration and scripting, not for high-performance or complex D-Bus client implementations. For very low-level D-Bus interactions or when precise message formatting is required, tools like <i>dbus-send</i> or direct D-Bus API programming might be preferred.


title: INTROSPECTION CAPABILITIES
content:
<i><b>qdbus</b></i> is excellent for D-Bus introspection. By gradually providing <i>service</i>, <i>path</i>, and <i>interface</i> arguments, one can explore the available methods, signals, and properties of any D-Bus exposed object, making it invaluable for discovering D-Bus APIs.


title: METHOD INVOCATION
content:
A primary use case for <i><b>qdbus</b></i> is invoking methods on D-Bus objects. This allows direct interaction with applications exposing D-Bus interfaces, enabling automation or debugging tasks directly from the command line, without needing to write dedicated client code.


title: HISTORY
content:
The <i><b>qdbus</b></i> utility was introduced as part of the Qt 4 framework, specifically with the <i>QtDBus</i> module. This module provided C++ bindings for the D-Bus protocol, simplifying inter-process communication for Qt applications. <i><b>qdbus</b></i> emerged as a convenient command-line frontend to these capabilities, enabling developers and administrators to easily inspect and interact with Qt applications exposing D-Bus interfaces. Its development has mirrored the evolution of the Qt framework, continuously providing a robust tool for D-Bus introspection and method invocation.


title: SYNOPSIS
content:
qemu-system-<i>[arch]</i> [<i>options</i>] [<i>disk_image</i>]<br>Example: <b>qemu-system-x86_64 -m 2G -smp 2 -drive file=./my_vm.qcow2,if=virtio -enable-kvm</b>


title: PARAMETERS
content:
<b>-m <i>&lt;size&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the RAM size for the virtual machine (e.g., 512M, 2G).<br><br><b>-cpu <i>&lt;model&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the CPU model for the guest (e.g., host, kvm64, qemu64).<br><br><b>-smp <i>&lt;cpus&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures the number of virtual CPUs and their topology (e.g., 2, cores=2,threads=1).<br><br><b>-drive <i>&lt;options&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a virtual disk drive, specifying file, interface, format (e.g., file=disk.img,if=virtio,format=qcow2).<br><br><b>-netdev <i>&lt;options&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures a network backend device (e.g., user,id=net0; tap,id=net1,ifname=tap0).<br><br><b>-device <i>&lt;dev_type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a virtual device to the guest, such as a network card or USB controller.<br><br><b>-M <i>&lt;machine&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the machine type or chipset architecture (e.g., pc, q35, virt).<br><br><b>-enable-kvm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables KVM acceleration for near-native performance on Linux hosts.<br><br><b>-vnc <i>&lt;display&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts a VNC server for remote graphical access (e.g., :0, 127.0.0.1:1).<br><br><b>-display <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the graphical display backend (e.g., sdl, gtk, none, vnc).<br><br><b>-usb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables USB support for the virtual machine.<br><br><b>-cdrom <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attaches an ISO image as a virtual CD-ROM drive.<br><br><b>-boot <i>&lt;order&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the boot device order (e.g., d=CD-ROM, c=hard disk, n=network).<br><br>


title: DESCRIPTION
content:
QEMU (Quick EMUlator) is a powerful, open-source virtualization and emulation solution. It operates in two primary modes: <i>full system emulation</i>, where it can run an entire operating system (e.g., Linux, Windows) for various architectures (x86, ARM, PowerPC) on a different host architecture, providing cross-architecture virtualization. Its other mode is <i>user-mode emulation</i>, allowing it to run programs compiled for a different CPU architecture directly on the host. When used on a Linux host with a compatible processor, QEMU can leverage the KVM (Kernel-based Virtual Machine) module to achieve near-native performance by directly utilizing the host's CPU virtualization extensions (e.g., Intel VT-x, AMD-V). This makes QEMU a fundamental component for running virtual machines, developing cross-platform software, and security research.


title: CAVEATS
content:
QEMU's performance without KVM acceleration can be significantly slower, as it relies on pure software emulation. KVM requires specific CPU virtualization extensions (Intel VT-x or AMD-V) enabled in the host's BIOS/UEFI. The command-line interface for QEMU can be complex and verbose, especially for advanced configurations. Exposing network ports or devices without proper security considerations can pose risks to the host system.


title: OPERATING MODES
content:
QEMU primarily operates in two distinct modes: <i>System Emulation</i>, where it emulates a complete machine (CPU, memory, devices) allowing an operating system to run. This mode supports cross-architecture virtualization (e.g., running an ARM OS on an x86 host). The second mode is <i>User-mode Emulation</i>, which allows QEMU to run single processes compiled for a different CPU architecture directly on the host operating system, without emulating a full system.


title: HISTORY
content:
QEMU was originally written by Fabrice Bellard and first released in 2003. It quickly gained popularity as an open-source alternative to commercial virtualization solutions. Its integration with the Linux KVM module in 2007 significantly boosted its performance, transforming it into a high-performance virtualizer. QEMU remains under active development by a large community, serving as a core component in many cloud platforms, embedded systems development, and research environments.


title: PARAMETERS
content:
<b>create</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Creates a new disk image of a specified size and format. It supports various options like preallocation, backing files, and cluster size.<br><br><b>convert</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Converts a disk image from one format to another. This is highly useful for migrating virtual disks between different hypervisors or optimizing storage.<br><br><b>check</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Checks the consistency and integrity of a disk image, particularly useful for QCOW2 images, identifying and reporting potential corruption.<br><br><b>info</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Displays detailed information about a disk image, including its format, virtual size, actual size on disk, backing file (if any), and snapshot details.<br><br><b>snapshot</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Manages snapshots within a disk image. This subcommand allows creating, applying, deleting, and listing snapshots, useful for saving and restoring VM states.<br><br><b>rebase</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Changes the backing file of a disk image. This is useful for consolidating chained images or changing the base image for a differencing disk.<br><br><b>resize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Resizes a disk image to a new specified size. It can expand or shrink images (though shrinking often requires filesystem changes within the guest).<br><br><b>amend</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Amends specific properties of an existing disk image without modifying its content.<br><br><b>measure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Measures the required space for certain operations, like converting an image to a new format.<br><br><b>map</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Dumps the virtual to physical page mapping of an image.<br><br><b>compare</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Compares two disk images to identify differences.<br><br><b>dd</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Copies data from an input path/image to an output path/image, similar to the <b>dd</b> command but for <b>qemu-img</b> supported formats.<br><br><b>sign</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Signs a disk image, useful for verifying integrity and authenticity.<br><br><b>verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Verifies the signature of a signed disk image.<br><br>


title: DESCRIPTION
content:
<b>qemu-img</b> is a powerful and versatile command-line utility included with the QEMU virtualization suite. It is indispensable for managing and manipulating disk images used by QEMU virtual machines.<br><br>This tool supports a wide array of disk image formats, including <i>QCOW2</i> (QEMU Copy-On-Write), <i>RAW</i>, <i>VMDK</i> (VMware), <i>VDI</i> (VirtualBox), <i>VHD</i> (Microsoft Virtual PC/Hyper-V), <i>VHDX</i> (Hyper-V's enhanced VHD), and others. <br><br>With <b>qemu-img</b>, users can perform essential operations such as creating new disk images, converting images between different formats, checking the integrity of existing images, gathering detailed information about them, managing snapshots, rebasing images on different backing files, and resizing image capacities. Its flexibility makes it a crucial component in various virtualization workflows, from setting up development environments and migrating virtual machines between different hypervisors to analyzing disk contents and optimizing storage usage in cloud or bare-metal virtualization platforms. It handles both fixed-size and sparse (growable) disk images, offering efficient storage management capabilities.


title: CAVEATS
content:
<b>Data Loss Risk:</b> <br>Operations like <i>resize</i>, <i>convert</i>, and <i>rebase</i> can potentially lead to data loss if interrupted or performed incorrectly. Always back up critical images before proceeding.<br><b>Performance:</b> <br>Converting or resizing large disk images can be a time-consuming and resource-intensive process. Ensure sufficient disk space and system resources are available.<br><b>Filesystem Management:</b> <br>While <b>qemu-img resize</b> changes the <i>disk image size</i>, it does not automatically resize the <i>filesystem</i> within the guest OS. This often requires separate guest OS tools (e.g., <b>parted</b>, <b>resize2fs</b>) to expand or shrink the filesystem to match the new disk size.<br><b>Format Compatibility:</b> <br>Not all disk image formats support all <b>qemu-img</b> features (e.g., snapshots are primarily a QCOW2 feature). Specific format limitations might apply.


title: SUPPORTED IMAGE FORMATS
content:
<b>qemu-img</b> boasts extensive support for numerous disk image formats, making it highly versatile for various virtualization environments. Key formats include: <br><i><b>RAW</b></i> (simple byte-for-byte copy, often sparse), <br><i><b>QCOW2</b></i> (QEMU Copy-On-Write, advanced features like snapshots, compression, encryption, and backing files), <br><i><b>QCOW</b></i> (older QEMU format), <br><i><b>VMDK</b></i> (VMware's Virtual Machine Disk format), <br><i><b>VDI</b></i> (VirtualBox Disk Image), <br><i><b>VHD</b></i> (Microsoft Virtual Hard Disk), <br><i><b>VHDX</b></i> (Microsoft's enhanced VHD format), <br><i><b>ISO</b></i> (CD/DVD images), and others like <i>cloop</i>, <i>host_device</i>, <i>parallels</i>, <i>vpc</i>, <i>bochs</i>.


title: BACKING FILES AND SNAPSHOTS
content:
A powerful feature of <b>qemu-img</b>, especially with <i>QCOW2</i>, is the concept of <i>backing files</i>. This allows creating a new image that only stores the differences from an existing base (backing) image. This is highly efficient for creating multiple virtual machines from a single master image or for managing disk snapshots. Snapshots, managed via <b>qemu-img snapshot</b>, capture the state of a disk at a specific point in time, enabling easy rollback and experimentation without affecting the base image.


title: HISTORY
content:
<b>qemu-img</b> has been an integral part of the QEMU project since its early days, evolving alongside the main QEMU emulator. Its development has closely mirrored the increasing sophistication of virtualization technologies and the need for robust disk image management. Initially supporting basic <i>RAW</i> and <i>QCOW</i> formats, it has continuously expanded its capabilities to include a vast array of disk image formats (like <i>VMDK</i>, <i>VHD</i>, <i>VDI</i>, <i>VHDX</i>) and advanced features such as sophisticated snapshot management, backing files, and efficient copy-on-write mechanisms (e.g., <i>QCOW2</i> improvements). Its ongoing development focuses on performance enhancements, broader format support, and improved integrity checks, making it a cornerstone utility for modern virtualization and cloud environments.


title: PARAMETERS
content:
<b><b>--layout</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads the specified layout/profile file upon startup. This allows automated loading of configurations for specific applications.<br><br><b><b>--no-gui</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts <i>qjoypad</i> without displaying the graphical user interface. It runs silently in the background, applying the configured mappings. Useful for system startup scripts.<br><br><b><b>--start-hidden</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches <i>qjoypad</i> hidden in the system tray instead of opening its main window. The icon will still be visible in the tray for easy access.<br><br><b><b>--delay</b> <i>&lt;ms&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Introduces a delay (in milliseconds) before <i>qjoypad</i> starts processing events. Can be useful if joystick devices take time to initialize after system boot.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of <i>qjoypad</i> and exits.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a brief help message with available command-line options and exits.<br><br>


title: DESCRIPTION
content:
<i>qjoypad</i> is a graphical Linux utility designed to map joystick and gamepad input events to keyboard presses and mouse movements/clicks. This allows users to control applications and games that do not natively support joysticks, by simulating keyboard and mouse input. It's particularly useful for playing older PC games, emulators, or controlling desktop environments with a gamepad. Users can create and save multiple profiles (layouts) tailored for different applications, enabling quick switching between configurations. The application runs primarily as a graphical user interface (GUI) but can also be launched in the background without a visible window, making it suitable for automatic startup.


title: CAVEATS
content:
<i>qjoypad</i> primarily relies on the X Window System (X11) for input simulation, which means its direct functionality might be limited or require compatibility layers (like XWayland) on modern Wayland-based desktop environments. <br>Development on <i>qjoypad</i> has been sporadic, and while generally stable, it might occasionally encounter compatibility issues with very new Linux kernels, joystick drivers, or specific hardware setups. Users might need to ensure proper permissions for joystick devices (e.g., being part of the 'input' group).


title: GRAPHICAL INTERFACE AND PROFILES
content:
The primary interaction with <i>qjoypad</i> is through its intuitive graphical interface. Users can easily assign keyboard keys, mouse buttons, mouse movements, and even complex macros to individual joystick axes and buttons. The ability to save and load multiple 'layout' or 'profile' files is a core feature, allowing users to quickly switch between different control schemes for various games or applications. These profiles store all mappings for a specific joystick and can be loaded via the GUI or command-line options.


title: BACKGROUND OPERATION
content:
While <i>qjoypad</i> is a GUI application, it can be configured to start automatically at system boot and run silently in the background using the <b>--no-gui</b> or <b>--start-hidden</b> options. This makes it ideal for users who want their joystick mappings active immediately without needing to manually launch the application's window each time.


title: HISTORY
content:
<i>qjoypad</i> emerged as a valuable tool in the early 2000s for Linux gamers and desktop users seeking to bridge the gap between joystick input and traditional keyboard/mouse controls. At a time when native gamepad support in Linux applications was less common, <i>qjoypad</i> provided a crucial solution for playing a wider range of games (especially Windows games via Wine) and improving accessibility. While newer solutions and Steam's Big Picture mode have gained prominence, <i>qjoypad</i> remains a lightweight and effective option for its specific niche.


title: PARAMETERS
content:
<b><b>--dryrun</b>, <b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulation of the cleanup process, showing which files and configurations would be removed without actually deleting anything. <i>Highly recommended for initial runs.</i><br><br><b><b>--verbose</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, providing more detailed information about the scanning and cleanup process.<br><br><b><b>--force</b>, <b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the cleanup without requiring user confirmation for deletions. <i>Use with extreme caution.</i><br><br><b><b>--storage &lt;storage_id&gt;</b>, <b>-s &lt;storage_id&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the cleanup operation to a specific storage ID, ensuring only orphaned files on that storage are processed.<br><br><b><b>--keep-days &lt;N&gt;</b>, <b>-k &lt;N&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of days to keep files or configurations that were last modified within this period. Files older than N days are considered for cleanup. Defaults to 7 days.<br><br><b><b>--keep-locks</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the removal of orphaned lock files.<br><br><b><b>--keep-orphaned-vmid-config</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the removal of orphaned VM/CT configuration files.<br><br><b><b>--keep-unused-disks</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the removal of unused disk images.<br><br>


title: DESCRIPTION
content:
<i>qm-cleanup</i> is a Proxmox VE utility designed to identify and remove orphaned or stale configuration files, lock files, and disk images associated with virtual machines and containers. These remnants can accumulate due to unexpected system reboots, failed VM/CT operations, or improper removals, leading to disk space wastage and potential inconsistencies. The command helps maintain a clean and efficient Proxmox environment by safely identifying and removing these unreferenced files, ensuring system stability and optimal resource utilization. It's often run with a dry-run first to preview changes before execution.


title: CAVEATS
content:
<ul><li><b><i>Root Permissions:</i></b> <i>qm-cleanup</i> must be run as root or with <i>sudo</i> to perform its operations.</li><li><b><i>Dry Run First:</i></b> Always perform a dry run (<b>--dryrun</b>) before executing the command to understand its impact and prevent unintended data loss.</li><li><b><i>Permanent Deletion:</i></b> Files removed by <i>qm-cleanup</i> are permanently deleted and cannot be recovered without backups.</li><li><b><i>Specific Purpose:</i></b> This command is for cleaning <i>orphaned</i> files, not for general disk space management or removing active VM/CT resources.</li></ul>


title: EXECUTION CONTEXT
content:
This command is specifically designed for Proxmox Virtual Environment installations. It relies on Proxmox's internal configuration and storage management to identify orphaned resources. Running it on a non-Proxmox system will not yield meaningful results.


title: SAFETY PRACTICES
content:
While <i>qm-cleanup</i> is designed to be safe, it's crucial to regularly back up your Proxmox configuration and critical VM/CT data. The <b>--dryrun</b> option is your first line of defense against accidental deletion.


title: HISTORY
content:
<i>qm-cleanup</i> is an integral part of the Proxmox VE ecosystem. It was introduced to address the common issue of stale or orphaned files accumulating in virtual environments, especially after crashes, power outages, or incomplete VM/CT deletion operations. Its design reflects the need for automated maintenance in large-scale virtualization deployments, evolving with Proxmox VE versions to improve scanning logic and user control over cleanup actions.


title: SYNOPSIS
content:
qm-cloud-init <B>&lt;VMID&gt;</B> [--hostname <I>&lt;name&gt;</I>] [--ipconfig<B>[n]</B> <I>&lt;value&gt;</I>] [--nameserver <I>&lt;ip&gt;</I>] [--searchdomain <I>&lt;domain&gt;</I>] [--ciuser <I>&lt;username&gt;</I>] [--cipassword <I>&lt;password&gt;</I>] [--sshkeys <I>&lt;keys&gt;</I>] [--timezone <I>&lt;zone&gt;</I>] [--meta-data <I>&lt;data&gt;</I>] [--user-data <I>&lt;data&gt;</I>] [--network-config <I>&lt;config&gt;</I>] [--force] [--debug]


title: PARAMETERS
content:
<b><B>&lt;VMID&gt;</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numerical ID of the virtual machine to configure.<br><br><b><B>--hostname</B> <I>&lt;name&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the hostname for the VM.<br><br><b><B>--ipconfig&lt;N&gt;</B> <I>&lt;value&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures network interface N (e.g., <B>--ipconfig0</B>). Value format is typically 'dhcp', 'static=<I>&lt;ip&gt;</I>/<I>&lt;cidr&gt;</I>,gateway=<I>&lt;gw&gt;</I>', or 'static=<I>&lt;ip&gt;</I>/<I>&lt;cidr&gt;</I>'.<br><br><b><B>--nameserver</B> <I>&lt;ip&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the DNS nameserver for the VM.<br><br><b><B>--searchdomain</B> <I>&lt;domain&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the DNS search domain for the VM.<br><br><b><B>--ciuser</B> <I>&lt;username&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the initial non-root user to be created in the VM.<br><br><b><B>--cipassword</B> <I>&lt;password&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the password for the specified <B>--ciuser</B>.<br><br><b><B>--sshkeys</B> <I>&lt;keys&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides public SSH keys to be added to the <B>--ciuser</B>'s authorized_keys file. Can be a path to a file or literal keys.<br><br><b><B>--timezone</B> <I>&lt;zone&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the system timezone inside the VM.<br><br><b><B>--meta-data</B> <I>&lt;data&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides custom <I>cloud-init</I> metadata as a YAML or JSON string.<br><br><b><B>--user-data</B> <I>&lt;data&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides custom <I>cloud-init</I> user data as a YAML or shell script string.<br><br><b><B>--network-config</B> <I>&lt;config&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides custom <I>cloud-init</I> network configuration as a YAML string. Overrides <B>--ipconfig</B> options.<br><br><b><B>--force</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the operation, potentially overwriting existing cloud-init configurations.<br><br><b><B>--debug</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output for troubleshooting.<br><br>


title: DESCRIPTION
content:
The <B>qm-cloud-init</B> command is a utility used within the Proxmox Virtual Environment (PVE) to facilitate the configuration of virtual machines (VMs) using <I>cloud-init</I>.<br><br>While <I>cloud-init</I> is a standard industry tool for initial setup of cloud instances, <B>qm-cloud-init</B> specifically helps in generating and applying the necessary configuration data for VMs managed by Proxmox. It allows administrators to define various aspects of a VM's initial state, such as hostname, network configuration, user accounts, and SSH keys, without manual intervention after the VM is created.<br><br>This command is particularly useful for automating VM deployments and creating standardized virtual machine templates. By providing parameters directly via the command line, <B>qm-cloud-init</B> generates the required <I>cloud-init</I> metadata and user data, which the VM consumes on its first boot, enabling seamless provisioning and customization.


title: CAVEATS
content:
Using <B>qm-cloud-init</B> effectively requires the target virtual machine's image or template to have the <I>cloud-init</I> agent installed and enabled. If the agent is not present or not properly configured, the cloud-init settings will not be applied on boot.<br><br>Changes made with <B>qm-cloud-init</B> (and subsequently applied via <B>qm set</B>) typically require the VM to be shut down and then started for the new configuration to take effect. Simply rebooting an already running VM might not re-trigger the <I>cloud-init</I> process.<br><br>Care should be taken when providing sensitive information like passwords directly on the command line, as they might be exposed in shell history or process listings.


title: INTEGRATION WITH <B>QM SET</B>
content:
While <B>qm-cloud-init</B> is used for generating cloud-init configuration, these configurations are typically applied to a VM using the <B>qm set</B> command. For instance, after generating the configuration using <B>qm-cloud-init</B>, one might use <B>qm set <I>&lt;VMID&gt;</I> --cloudinit <I>&lt;storage_id&gt;</I></B> to link the cloud-init drive, or directly pass parameters like <B>qm set <I>&lt;VMID&gt;</I> --ciuser <I>&lt;username&gt;</I></B> which implicitly uses <B>qm-cloud-init</B> logic internally. The direct usage of <B>qm-cloud-init</B> allows for more granular control over the generated cloud-init data, potentially for debugging or custom scenarios.


title: HISTORY
content:
<B>qm-cloud-init</B> emerged as part of Proxmox Virtual Environment's (PVE) efforts to streamline virtual machine provisioning and embrace standard cloud methodologies. It was introduced to simplify the creation and customization of VMs by leveraging <I>cloud-init</I>, which became increasingly popular for automated instance setup in cloud environments. Its development paralleled the growing demand for more robust and automated VM lifecycle management within PVE, making it easier for users to deploy pre-configured instances from templates.


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numerical identifier of the virtual machine or container for which the cloud-init configuration should be dumped.<br><br>


title: DESCRIPTION
content:
<i>qm-cloudinit-dump</i> is a utility command provided by Proxmox Virtual Environment (PVE) as part of its management toolkit.<br><br>Its primary function is to retrieve and display the <b>user-data</b> configuration that has been generated or set for a specific virtual machine (VM) or container (CT) using Proxmox's integrated cloud-init functionality.<br><br>Cloud-init is an industry-standard mechanism for cross-platform cloud instance initialization. Proxmox leverages it to automate initial setup tasks such as setting hostnames, configuring network interfaces, injecting SSH keys, and executing custom scripts during the first boot of a VM or CT.<br><br>This command is invaluable for administrators to verify precisely what <b>user-data</b> cloud-init will consume on the guest. This aids significantly in troubleshooting cloud-init related issues or validating that the intended configuration is being passed to the VM/CT upon its first boot.<br><br>The output typically presents the <b>user-data</b> in a human-readable format, usually YAML, reflecting the settings configured either through the Proxmox web UI or via command-line tools like <i>qm set</i>.


title: CAVEATS
content:
This command requires the VM or container specified by <i>&lt;vmid&gt;</i> to exist and have cloud-init enabled or previously configured.<br><br>It only dumps the <b>user-data</b> that Proxmox itself generates or stores for cloud-init. It does <b>not</b> interact with the running guest OS or show what cloud-init has actually executed or consumed inside the VM/CT.<br><br>The output format is typically YAML.<br><br>Execution usually requires root privileges or <i>sudo</i> access on the Proxmox host.


title: OUTPUT FORMAT
content:
The output produced by <i>qm-cloudinit-dump</i> is standard cloud-init <b>user-data</b>, typically presented in YAML format. This format is widely recognized and can be easily parsed by other tools or used for documentation and verification purposes.


title: DIAGNOSTIC UTILITY
content:
While not a configuration tool itself, <i>qm-cloudinit-dump</i> serves as an essential diagnostic utility. It helps Proxmox administrators quickly ascertain the exact cloud-init configuration that Proxmox intends to provide to a guest, which is crucial for debugging provisioning failures or unexpected guest behavior.


title: HISTORY
content:
<i>qm-cloudinit-dump</i> emerged as part of the Proxmox Virtual Environment suite, developed in conjunction with PVE's enhanced cloud-init integration features. This integration became a more prominent and stable feature in Proxmox VE versions 5.x and 6.x onwards, aiming to streamline and automate the deployment and initial configuration of virtual machines and containers.


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier (ID) of the virtual machine or container from which the snapshot will be deleted.<br><br><b><i>&lt;snapname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the snapshot to be deleted. This name must exactly match an existing snapshot for the specified VM/CT.<br><br><b><b>--force</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <I>1</I> (true), the command will attempt to force the deletion of the snapshot, even if there are potential issues or dependencies. Use with extreme caution as this can lead to data inconsistency if not fully understood.<br><br><b><b>--children</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <I>1</I> (true), all direct and indirect children (descendants) of the specified snapshot will also be deleted recursively. This option is useful for cleaning up an entire branch of the snapshot tree. Introduced in Proxmox VE 7.2.<br><br>


title: DESCRIPTION
content:
The <b>qm-delsnapshot</b> command, part of the Proxmox Virtual Environment (PVE) toolkit, is used to remove existing snapshots of a KVM virtual machine or LXC container. A snapshot captures the complete state of a VM or container at a specific point in time, including its configuration, disk images, and optionally memory state. Deleting a snapshot frees up the disk space occupied by the snapshot's delta changes and removes its entry from the snapshot history. This command is crucial for managing storage space, cleaning up old or unnecessary recovery points, and maintaining a streamlined snapshot history. It ensures that the VM's or container's state and data are no longer tied to that specific snapshot point, allowing for better resource management and system organization.


title: CAVEATS
content:
Deleting snapshots frees disk space, but the actual space reclamation might depend on the underlying storage technology (e.g., ZFS, LVM thin, QCOW2) and might not be immediately apparent.<br>Carefully consider the snapshot hierarchy. Deleting a parent snapshot without the <b>--children</b> option might render its child snapshots unusable if they depend on the parent's data, although Proxmox usually prevents this or merges data where possible. Using <b>--children</b> will remove the entire branch.<br>Ensure the VM or container is not currently rolled back to or running on the snapshot you intend to delete, as this could lead to unexpected behavior or data loss.<br>Always double-check the <I>vmid</I> and <I>snapname</I> to prevent accidental deletion of important snapshots.


title: SNAPSHOT TYPES AND DEPENDENCIES
content:
Proxmox snapshots can include disk state and optionally memory state. Disk snapshots are typically differential, storing only changes since the previous snapshot or the base disk. This creates a dependency chain, where deleting a snapshot can impact subsequent snapshots. Understanding this chain is crucial for effective snapshot management.


title: STORAGE BACKEND IMPACT
content:
The behavior of <b>qm-delsnapshot</b> can subtly differ based on the underlying storage backend. For instance, ZFS snapshots are native filesystem snapshots, while LVM thin provisioned volumes use LVM snapshots, and QCOW2 images manage their own internal snapshots. Each backend handles block allocation and deallocation differently when a snapshot is deleted, influencing performance and space reclamation.


title: HISTORY
content:
Snapshot management has been a core feature of Proxmox VE since its early versions, essential for backup and recovery strategies. The <b>qm-delsnapshot</b> command, along with its counterparts for creation and listing, has evolved to provide robust point-in-time recovery capabilities. The introduction of the <b>--children</b> option in Proxmox VE 7.2 enhanced the command's functionality by simplifying the deletion of entire snapshot branches, reflecting continuous improvements in snapshot tree management and user convenience.


title: SYNOPSIS
content:
<b>qm destroy</b> <i>&lt;vmid&gt;</i> [<i>OPTIONS</i>]<br><br><i>&lt;vmid&gt;</i>: The <i>unique numerical identifier</i> for the virtual machine or container to destroy. This is a mandatory argument.


title: PARAMETERS
content:
<b>--force <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <b>--force 1</b> to forcibly destroy the VM/CT even if it is running. Without this, the command will fail if the VM/CT is still active. Defaults to 0 (false).<br><br><b>--purge <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <b>--purge 1</b> to remove all backups and log entries associated with the VM/CT. Defaults to 0 (false).<br><br><b>--skiplog <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <b>--skiplog 1</b> to prevent the creation of a log entry for this destroy operation. Defaults to 0 (false).<br><br>


title: DESCRIPTION
content:
<i>qm-destroy</i> is a command-line utility used within the Proxmox VE (Virtual Environment) ecosystem to permanently delete a virtual machine (VM) or container (CT). When executed, it removes the VM/CT's configuration file, all associated virtual disk images, and any snapshots. This operation is irreversible and results in complete data loss for the specified VM or container.<br><br>It's a critical management tool for freeing up resources and decluttering the Proxmox host. Users must be cautious when using this command due to its destructive nature, always ensuring that critical data has been backed up before proceeding.


title: CAVEATS
content:
This command performs an <i>irreversible</i> operation. All data associated with the specified VM or container, including its configuration, virtual disks, and snapshots, will be permanently deleted.<br><br>Ensure you have backed up any critical data before using <i>qm-destroy</i>.<br><br>Using <b>--force</b> on a running VM can lead to data corruption if the guest OS is not properly shut down beforehand. It is always recommended to stop the VM gracefully (e.g., using <i>qm stop</i>) before destroying it.


title: VMID SIGNIFICANCE
content:
The <i>vmid</i> is a crucial identifier in Proxmox VE. It must be unique across all VMs and containers on a Proxmox host. It's used in almost all <i>qm</i> and <i>pct</i> commands to specify the target VM or container.


title: DATA LOCATION
content:
When <i>qm-destroy</i> is executed, it removes configuration files typically located in <i>/etc/pve/qemu-server/</i> (for KVM VMs) or <i>/etc/pve/lxc/</i> (for LXC containers), and also deletes associated disk images from the configured storage.


title: HISTORY
content:
<i>qm-destroy</i> is an integral part of the <I>Proxmox Virtual Environment (PVE)</I>, an open-source server virtualization management solution. Proxmox VE was first released in 2007, building upon Debian Linux and integrating KVM for virtual machines and LXC for containers. The <i>qm</i> utility suite, including <i>qm-destroy</i>, has been a core component of PVE's command-line interface from its early days, providing robust control over the lifecycle of VMs and containers. Its design reflects the need for powerful and efficient management of virtualized environments.


title: PARAMETERS
content:
<b>vmid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier of the virtual machine to which the disk will be imported.<br><br><b>source-file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The absolute path to the disk image file (e.g., <i>.raw</i>, <i>.qcow2</i>, <i>.vmdk</i>) on the Proxmox host to be imported.<br><br><b>target-storage</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ID of the Proxmox storage pool or volume group where the new disk will be created and stored.<br><br><b>--format <I>&lt;fmt&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target disk image format for the imported disk (e.g., <i>raw</i>, <i>qcow2</i>). If omitted, the default format of the target storage is used.<br><br><b>--disk <I>&lt;disk_id&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a specific PCI/SCSI/SATA ID to the new disk (e.g., <i>scsi0</i>, <i>sata1</i>). If not specified, Proxmox automatically assigns the next available ID.<br><br><b>--sparse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to create a sparse file if the target storage supports it, meaning only blocks with data are allocated, saving space.<br><br><b>--lvmthin-max-size <I>&lt;GB&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For LVM-Thin storage, sets a maximum size for the imported volume, allowing for over-provisioning if desired.<br><br><b>--raw-format <I>&lt;fmt&gt;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the original format of the source file, particularly useful if the file extension does not accurately reflect its content (e.g., a <i>.raw</i> file that is actually a QCOW2 image).<br><br>


title: DESCRIPTION
content:
The <i>qm-disk-import</i> command is a crucial utility within the Proxmox Virtual Environment (PVE) for importing existing disk images into a virtual machine's storage. It facilitates the migration of virtual disks from other hypervisors or raw disk files directly into Proxmox-managed storage. The command handles various disk image formats, such as RAW, QCOW2, and VMDK, automatically converting them to the appropriate format for the target storage type (e.g., LVM, ZFS, file-based). <br><br>This tool simplifies the process of attaching new disks to a VM or replacing existing ones, abstracting away the complexities of manual format conversions and storage provisioning. It's commonly used when moving VMs from other platforms, or when preparing pre-built disk images for use within Proxmox.


title: CAVEATS
content:
<ul><li><b>Disk Space</b>: Ensure the <i>target-storage</i> has sufficient free space for the imported disk, especially if converting to a non-sparse format.</li><li><b>Import Time</b>: Importing large disk images can take a significant amount of time, depending on disk size, storage speed, and server load.</li><li><b>VM State</b>: It's generally recommended to perform disk imports while the target VM is powered off to avoid potential data corruption or inconsistencies.</li><li><b>Format Compatibility</b>: While the command handles many formats, ensuring the source disk image is healthy and compatible with QEMU/KVM is crucial.</li></ul>


title: TYPICAL WORKFLOW
content:
A common use case involves downloading a pre-built VM image (e.g., an appliance from a vendor), converting it to a raw or qcow2 format if necessary (e.g., using <i>qemu-img convert</i>), copying it to the Proxmox host, and then using <i>qm-disk-import</i> to attach it to a new or existing VM.


title: STORAGE TYPES
content:
The command adapts its behavior based on the <i>target-storage</i> type. For LVM, it creates an LVM volume; for ZFS, a ZFS dataset; and for directory-based storage, a file on the filesystem.


title: HISTORY
content:
The <i>qm-disk-import</i> command is an integral part of the Proxmox Virtual Environment (PVE) suite, which originated in 2007. As Proxmox VE evolved into a comprehensive virtualization and container platform, tools like <i>qm-disk-import</i> were developed to simplify common administrative tasks, such as migrating virtual machines from other hypervisors or integrating pre-built images. Its inclusion reflects Proxmox's focus on ease-of-use and robust management of heterogeneous disk formats and storage backends.


title: SYNOPSIS
content:
<b>qm-disk-move</b> <i>&lt;vmid&gt; &lt;disk&gt; &lt;target-storage&gt;</i> [OPTIONS]<br>Example: <b>qm-disk-move</b> <i>100 scsi0 local-lvm</i> <b>--format</b> <i>qcow2</i> <b>--bwlimit</b> <i>102400</i>


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ID of the virtual machine whose disk is to be moved.<br><br><b><i>&lt;disk&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The identifier of the disk to be moved (e.g., <i>scsi0</i>, <i>ide1</i>, <i>virtio0</i>).<br><br><b><i>&lt;target-storage&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ID of the Proxmox storage pool where the disk will be moved.<br><br><b><b>--bwlimit</b> <i>&lt;integer&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the bandwidth for the disk move operation in kB/s. Useful to prevent excessive network or storage load during transfers.<br><br><b><b>--delete-old-disk</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies whether the original disk should be deleted from the source storage after a successful move. Defaults to <i>true</i>.<br><br><b><b>--format</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the target image format for the disk (e.g., <i>raw</i>, <i>qcow2</i>, <i>vmdk</i>). If not specified, the original format or a default for the target storage is used.<br><br><b><b>--sparse</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables sparse allocation for the target disk image. Applicable for formats like <i>qcow2</i> or <i>vmdk</i>. Defaults to <i>true</i> where supported.<br><br><b><b>--target-disk</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows specifying a new disk ID for the moved disk on the target storage (e.g., <i>scsi1</i>). If omitted, the command attempts to reuse the existing disk ID.<br><br><b><b>--target-node</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a target node for the move operation. Relevant in clustered environments for specific shared storage setups or for offline moves across nodes.<br><br><b><b>--wait</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines whether the command should wait for the disk move operation to complete before exiting. Defaults to <i>true</i>.<br><br>


title: DESCRIPTION
content:
<b>qm-disk-move</b> is a Proxmox VE command-line utility designed to migrate a virtual machine's disk from one storage location to another. This powerful tool allows administrators to efficiently reorganize their storage infrastructure, balance I/O loads, or move disks to different types of storage (e.g., from local to shared, or from HDD to SSD).<br><br>The command handles the entire process: it clones the source disk to the specified target storage, updates the VM's configuration to point to the new disk, and optionally deletes the original disk. Depending on the storage types and configuration, the move operation can be performed online (while the VM is running) for certain shared storage configurations, or it might require the VM to be shut down. It provides options to control bandwidth, target format, sparse allocation, and whether the old disk is automatically removed after a successful transfer. This flexibility makes <b>qm-disk-move</b> an essential tool for Proxmox VE storage management.


title: CAVEATS
content:
<ul><li>For certain storage types (e.g., local storage) or when moving disks between different Proxmox nodes without shared storage, the virtual machine typically needs to be shut down (offline) before the disk move operation can begin.</li><li>Ensure the target storage has sufficient free space to accommodate the disk, especially if converting to a non-sparse format or a format with a larger overhead.</li><li>If <b>--delete-old-disk</b> is set to <i>false</i>, the original disk will remain, requiring manual cleanup.</li><li>Bandwidth limits (<b>--bwlimit</b>) can significantly extend the time required for the operation, particularly for large disks.</li></ul>


title: LIVE MIGRATION CONSIDERATIONS
content:
<b>qm-disk-move</b> can sometimes be used for 'live' disk migration (VM remains running) if the underlying storage supports features like shared storage and atomic updates. However, for non-shared storage or specific configurations, it is generally safer and often required that the VM is offline before initiating the disk move.


title: VM CONFIGURATION UPDATES
content:
When a disk is moved, the virtual machine's configuration file (typically located at <i>/etc/pve/qemu-server/&lt;vmid&gt;.conf</i>) is automatically updated by Proxmox VE to reflect the new disk location and properties. If the <b>--target-disk</b> option is used, the disk ID within the VM configuration will also be updated accordingly.


title: HISTORY
content:
<b>qm-disk-move</b> is an integral part of Proxmox Virtual Environment (PVE), a Debian-based virtualization management solution. Its development is tied directly to the evolution of PVE, which originated in 2007. As Proxmox VE matured, so did its storage management capabilities, leading to the introduction and refinement of tools like <b>qm-disk-move</b> to facilitate flexible and robust handling of virtual machine disks across various storage backends. It reflects the ongoing need for efficient storage migration in dynamic virtualized environments, enabling administrators to adapt to changing storage requirements without complex manual procedures.


title: PARAMETERS
content:
<b>vmid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID of the Qemu guest virtual machine.<br><br><b>disk</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The identifier of the virtual disk to resize (e.g., 'scsi0', 'ide0', 'virtio0', 'sata0').<br><br><b>size</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target size for the disk. Can be an absolute size (e.g., '32G', '1T') or a relative change (e.g., '+10G', '-2G').<br><br><b>--format <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target image format (e.g., 'qcow2', 'raw') when resizing certain disk types. Only applicable if the backend allows format changes.<br><br><b>--sparse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables sparse allocation for the resized image, meaning disk blocks are only allocated as data is written.<br><br><b>--dryrun</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a simulated resize operation without making any actual changes to the disk. Useful for validating parameters.<br><br>


title: DESCRIPTION
content:
The <I>qm-disk-resize</I> command in Proxmox VE facilitates the resizing of virtual disks attached to Qemu guests. This powerful utility allows administrators to either increase or decrease the storage capacity of a VM's disk, providing flexibility in managing virtual machine resources. It supports various storage backends, including local directories, LVM, ZFS, and Ceph.<br><br>When increasing a disk's size, it's typically a safe operation from a data integrity perspective, though it usually necessitates an additional step of expanding the filesystem <I>within</I> the guest operating system to utilize the newly available space. Conversely, decreasing a disk's size is a highly critical operation that carries a significant risk of data loss if not performed with extreme caution. Before attempting to shrink a disk, the filesystem inside the guest <B>must</B> be shrunk to a size smaller than the target disk size. Failure to do so will result in data corruption.<br><br>The command offers options for specifying the new size (absolute or relative), setting the image format for certain storage types, and a dry-run mode to preview changes without committing them. While some setups might support live resizing, it is generally recommended to stop the virtual machine before performing disk resize operations to ensure data consistency and avoid potential issues. Always back up your virtual machine before undertaking disk resizing to prevent unforeseen data loss.


title: CAVEATS
content:
Resizing disks, especially decreasing their size, carries inherent risks.<br><b>Decreasing a disk</b>: This operation is extremely dangerous if the filesystem inside the guest is not shrunk <I>before</I> the disk. Data loss is highly probable if the guest filesystem occupies space beyond the new disk size.<br><b>Increasing a disk</b>: While generally safer, the guest operating system's filesystem will need to be explicitly expanded to utilize the newly available space.<br><b>VM State</b>: For most storage types and configurations, the VM should be powered off before resizing. Live resize capabilities are limited and highly dependent on storage type and guest OS support.<br><b>Snapshots</b>: Having active snapshots might prevent disk resizing operations.<br><b>Backup</b>: Always create a full backup of the VM before attempting any disk resize operation.


title: HISTORY
content:
The <I>qm-disk-resize</I> command is an integral part of the Proxmox VE (Virtual Environment) suite, designed to provide flexible disk management for Qemu-KVM virtual machines. Its development has mirrored the evolution of Proxmox VE itself, adapting to support new storage technologies like ZFS, Ceph, and various LVM setups, while continuously improving the robustness and safety of disk operations. It was introduced to simplify disk adjustments directly from the Proxmox CLI, abstracting the underlying <I>qemu-img</I> operations for various storage backends.


title: SYNOPSIS
content:
The functionality implied by "qm-guest-cmd" is typically accessed via the `<b>qm guest</b>` subcommands. Here are common usage patterns:<br><br><b>For executing arbitrary shell commands inside the guest:</b><br>&nbsp;&nbsp;&nbsp;<b>qm guest exec</b> <I><b>&lt;vmid&gt;</b></I> <I><b>&lt;command&gt;</b></I> [ <I><b>&lt;arg1&gt;</b></I> ... ] [<i>--timeout &lt;N&gt;</i>] [<i>--input &lt;filename&gt;</i>] [<i>--env &lt;ENVVAR=VALUE&gt;</i>]<br><br><b>For sending specific QEMU Guest Agent API commands:</b><br>&nbsp;&nbsp;&nbsp;<b>qm guest cmd</b> <I><b>&lt;vmid&gt;</b></I> <I><b>&lt;guest-agent-command&gt;</b></I> [ <I><b>&lt;arg1&gt;</b></I> ... ] [<i>--timeout &lt;N&gt;</i>]<br><br><b>Examples of other common guest operations:</b><br>&nbsp;&nbsp;&nbsp;<b>qm guest info</b> <I><b>&lt;vmid&gt;</b></I><br>&nbsp;&nbsp;&nbsp;<b>qm guest fsinfo</b> <I><b>&lt;vmid&gt;</b></I><br>&nbsp;&nbsp;&nbsp;<b>qm guest ping</b> <I><b>&lt;vmid&gt;</b></I><br>&nbsp;&nbsp;&nbsp;<b>qm guest shutdown</b> <I><b>&lt;vmid&gt;</b></I> [<i>--force</i>] [<i>--timeout &lt;N&gt;</i>]<br>&nbsp;&nbsp;&nbsp;<b>qm guest reboot</b> <I><b>&lt;vmid&gt;</b></I> [<i>--timeout &lt;N&gt;</i>]


title: PARAMETERS
content:
<b><I><b>&lt;vmid&gt;</b></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID of the virtual machine on the Proxmox host.<br><br><b><I><b>&lt;command&gt;</b></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The shell command to execute inside the guest (used with `<b>qm guest exec</b>`).<br><br><b><I><b>&lt;arg1&gt; ...</b></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional arguments to pass to the shell command or guest agent command.<br><br><b><i>--timeout &lt;N&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maximum time in seconds to wait for the command to complete. Defaults to 10 seconds.<br><br><b><i>--input &lt;filename&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads standard input for the guest command from the specified file on the host (used with `<b>qm guest exec</b>`).<br><br><b><i>--env &lt;ENVVAR=VALUE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets an environment variable for the executed command (used with `<b>qm guest exec</b>`). Can be specified multiple times.<br><br><b><I><b>&lt;guest-agent-command&gt;</b></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A specific command directly supported by the QEMU Guest Agent API (used with `<b>qm guest cmd</b>`). Common examples include: `<b>get-osinfo</b>`, `<b>get-fsinfo</b>`, `<b>get-ip-addresses</b>`, `<b>guest-ping</b>`, `<b>guest-shutdown</b>`, `<b>guest-reboot</b>`.<br><br>


title: DESCRIPTION
content:
The `<b>qm-guest-cmd</b>` functionality, primarily accessed through the `<b>qm guest</b>` subcommand in Proxmox Virtual Environment (PVE), enables a Proxmox host to execute commands and retrieve information directly from a running QEMU/KVM virtual machine's guest operating system. This powerful feature relies on the `<b>qemu-guest-agent</b>` package being installed and operational within the guest VM. It establishes a communication channel (typically via virtio-serial) that allows the host to send API calls and receive responses from the agent. <br><br>Common uses include: retrieving guest IP addresses (`<b>qm guest info</b>`), querying filesystem information (`<b>qm guest fsinfo</b>`), executing arbitrary shell commands (`<b>qm guest exec</b>`), gracefully shutting down or rebooting the guest (`<b>qm guest shutdown</b>`, `<b>qm guest reboot</b>`), and synchronizing guest filesystem caches (`<b>qm guest sync</b>`). This capability is invaluable for automation, monitoring, and remote administration of guest VMs without needing direct network access or SSH, making it a cornerstone for managing a Proxmox cluster.


title: CAVEATS
content:
The `<b>qemu-guest-agent</b>` package <i>must</i> be installed and running inside the target virtual machine for any `<b>qm guest</b>` commands to function. Without it, commands will fail.<br>The term "qm-guest-cmd" itself is often a conceptual shorthand for using the `<b>qm guest</b>` subcommands within Proxmox VE, as `qm-guest-cmd` is not a standalone executable or commonly documented command.<br>Executing commands with `<b>qm guest exec</b>` means they run with root privileges inside the guest by default, which can be a security risk if not used carefully.


title: IMPORTANT DEPENDENCIES
content:
The most critical dependency for `<b>qm guest</b>` functionality is the `<b>qemu-guest-agent</b>` software package, which must be installed and actively running within the guest virtual machine. Without it, the host cannot communicate with the guest OS via this mechanism.


title: COMMON USE CASES
content:
 - <i>Automated VM Shutdown/Reboot:</i> Gracefully power down or restart VMs from the Proxmox host, ensuring data integrity.<br> - <i>IP Address Retrieval:</i> Easily get the IP address(es) of a guest without needing to log in to the VM.<br> - <i>Filesystem Information:</i> Query disk usage, available space, and mounted filesystems within the guest.<br> - <i>Monitoring and Scripting:</i> Execute custom scripts or commands inside the guest for monitoring, configuration, or data collection purposes from host-side automation.


title: HISTORY
content:
The QEMU Guest Agent (QGA) was developed as an integral part of the QEMU virtualization project to improve communication and integration between the host and guest operating systems. Proxmox Virtual Environment (PVE) adopted and deeply integrated the QGA functionality, making it a cornerstone for advanced VM management capabilities. Over time, the `<b>qm guest</b>` subcommands evolved to expose a rich set of guest agent features directly through the Proxmox CLI, simplifying operations like graceful shutdowns, IP address retrieval, and command execution, which previously required direct SSH or other network-based access to the guest.


title: SYNOPSIS
content:
<b>qm guest exec</b> <I>&lt;vmid&gt;</I> <b>--command</b> <I>&lt;string&gt;</I> [<b>--args</b> <I>&lt;array&gt;</I>] [<b>--input</b> <I>&lt;string&gt;</I>] [<b>--timeout</b> <I>&lt;integer&gt;</I>] [<b>--verbose</b> <I>&lt;boolean&gt;</I>]


title: PARAMETERS
content:
<b>vmid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID of the virtual machine where the command will be executed.<br><br><b>--command <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full path to the command or executable to run inside the guest, e.g., <i>/usr/bin/ls</i>.<br><br><b>--args <array></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A list of arguments to pass to the specified command. Each argument should be provided as a separate item, e.g., <i>'--args', '/tmp', '-l'</i>.<br><br><b>--input <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Base64 encoded data that will be piped to the standard input (stdin) of the executed command.<br><br><b>--timeout <integer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a timeout (in seconds) for the command execution. If the command does not complete within this period, it will be terminated. The default is 60 seconds.<br><br><b>--verbose <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <i>true</i>, the command's standard output (stdout) and standard error (stderr) will be included in the <i>qm-guest-exec</i>'s output on the host. By default, only the exit status is returned.<br><br>


title: DESCRIPTION
content:
<i>qm-guest-exec</i> is a powerful command-line utility provided by Proxmox VE that allows the execution of arbitrary commands directly inside a running virtual machine's guest operating system from the Proxmox host. It leverages the <b>QEMU Guest Agent</b> (qemu-guest-agent) service, which must be installed and active within the guest VM. This command is invaluable for automation, scripting routine maintenance tasks, or retrieving information without needing network access or SSH credentials to the guest. It streamlines VM management by providing a direct communication channel, enabling administrators to manage guest OS functionalities, install software, or check system status remotely and efficiently.


title: CAVEATS
content:
<ul><li><b>QEMU Guest Agent Requirement</b>: The <i>qemu-guest-agent</i> package must be installed and actively running within the target guest VM. Without it, <i>qm-guest-exec</i> cannot communicate with the guest.</li><br><li><b>Guest Status</b>: The virtual machine must be powered on and running for the command to execute successfully.</li><br><li><b>Permissions</b>: Commands executed via <i>qm-guest-exec</i> typically run with elevated privileges (e.g., as <i>root</i> on Linux or <i>SYSTEM</i> on Windows) within the guest OS, depending on the guest agent's configuration. Exercise caution when executing commands.</li><br><li><b>Output Handling</b>: By default, <i>qm-guest-exec</i> only returns the command's exit status. To see the standard output and standard error, the <i>--verbose true</i> option must be used.</li><br><li><b>Timeout Behavior</b>: Commands exceeding the specified or default timeout will be terminated. Ensure the timeout is sufficient for long-running tasks.</li></ul>


title: EXIT STATUS
content:
The <i>qm-guest-exec</i> command returns the exit status of the command executed within the guest. A status of <b>0</b> generally indicates success, while a non-zero value indicates an error.


title: BASE64 ENCODING FOR INPUT
content:
When using the <i>--input</i> option, the data must be supplied in Base64 encoded format. For example, to pass 'Hello, World!' to a command, you would first encode it: <i>echo "Hello, World!" | base64</i>, then use the resulting Base64 string with <i>--input</i>.


title: PRACTICAL EXAMPLES
content:
To check the uptime of a VM with ID <i>101</i>:<br> <code>qm guest exec 101 --command /usr/bin/uptime --verbose true</code><br><br>To create a file named <i>/tmp/testfile.txt</i> with content 'This is content' in VM <i>102</i>:<br> <code>qm guest exec 102 --command /usr/bin/tee --args /tmp/testfile.txt --input $(echo 'This is content' | base64) --verbose true</code>


title: HISTORY
content:
The capability to interact directly with guest operating systems via the QEMU Guest Agent has been a significant enhancement in virtualization platforms like Proxmox VE. While the QEMU Guest Agent itself has evolved over time, <i>qm-guest-exec</i> and similar functionalities were integrated into Proxmox VE to provide a robust, out-of-band management channel. This feature aims to improve automation, simplify guest maintenance, and enhance the overall manageability of virtualized environments without relying on traditional network-based access methods like SSH or WinRM, thereby increasing security and efficiency.


title: PARAMETERS
content:
<b><I>vmid</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier (ID) of the virtual machine on which the command was executed.<br><br><b><I>cmdid</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID returned by the <I>qm-guest-exec</I> command when the task was initially submitted to the guest agent.<br><br>


title: DESCRIPTION
content:
This command retrieves the status of a previously executed command within a <b>QEMU/KVM guest virtual machine</b>, managed by the <I>qemu-guest-agent</I>. It's typically used in conjunction with <I>qm-guest-exec</I> (or similar commands) which submits the command to the guest.<br><br>The guest agent executes the command and reports its status back to the host. <I>qm-guest-exec-status</I> allows the host to query if the command succeeded, failed, or is still running, and often provides the command's standard output and error streams, as well as its exit code. This is crucial for automation and orchestrating operations within virtual machines from the hypervisor host. It significantly aids in validating the success or failure of tasks like software installations, configuration changes, or script executions initiated from the host side.


title: CAVEATS
content:
Requires the <I>qemu-guest-agent</I> to be installed, running, and enabled within the guest VM.<br>Network or communication issues between the host and guest agent can lead to timeouts or failed status retrieval.<br>The <I>cmdid</I> is a transient identifier, valid only for the specific command execution it represents.


title: OUTPUT FORMAT
content:
The command typically returns a JSON object containing details about the executed command, including its <I>status</I> (e.g., 'running', 'succeeded', 'failed'), the <I>exit-code</I>, and captured <I>stdout</I> and <I>stderr</I> streams if available.


title: HISTORY
content:
This command is an integral part of the <I>Proxmox VE</I> virtualization management suite, which builds upon <I>QEMU/KVM</I> technologies.<br><br>Its development is closely tied to the evolution of the <I>QEMU Guest Agent</I> functionality, which introduced a robust channel for host-guest communication. Proxmox VE leverages these capabilities to offer advanced VM management features, including the ability to execute commands remotely and query their status. This command, along with <I>qm-guest-exec</I>, enables powerful automation and orchestration workflows for virtual machines managed by Proxmox VE.


title: SYNOPSIS
content:
<b>qm guest passwd</b> <i>&lt;vmid&gt; &lt;username&gt; [&lt;password&gt;] [OPTIONS]</i><br><br><i>&lt;vmid&gt;</i>: The numeric ID of the virtual machine to target.<br><i>&lt;username&gt;</i>: The username inside the guest VM whose password is to be changed (e.g., 'root', 'administrator').<br><i>[&lt;password&gt;]</i>: Optional. The new password to set. If omitted, the command might prompt for it interactively for security, or the guest agent might reset it to an empty/disabled state depending on the guest OS and agent capabilities.


title: PARAMETERS
content:
<b>--timeout <integer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum timeout in seconds for the guest agent command to complete. The default value is typically 60 seconds.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, providing more detailed information about the execution process.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output, showing even more low-level details, useful for troubleshooting issues.<br><br><b>--ignore-lock</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the command to execute even if the VM is locked (e.g., by another task). Use with caution as it can lead to inconsistencies if concurrent operations are not handled properly.<br><br>


title: DESCRIPTION
content:
The <b>`qm guest passwd`</b> command, an integral part of the <b>Proxmox VE</b> (Virtual Environment) suite, empowers administrators to remotely set or reset the password for a designated user within a <b>QEMU/KVM virtual machine</b>. This powerful utility operates by establishing communication with the <b>QEMU Guest Agent (`qemu-ga`)</b>, which must be installed and running inside the guest operating system. Its primary purpose lies in facilitating password recovery when guest OS access is compromised, or for streamlining the initial configuration and automation of VM deployments. The command is versatile, supporting various guest operating systems, including common Linux distributions and Windows, provided the `qemu-ga` service is active and functional.


title: CAVEATS
content:
This command <b>requires the QEMU Guest Agent (`qemu-ga`) to be installed, running, and properly configured</b> within the target guest virtual machine. The `guest-agent` option must also be enabled for the VM in Proxmox's hardware settings.<br>The guest OS must support the password-setting functionality via `qemu-ga`. This works reliably on most modern Linux distributions and Windows.<br>Passing the password directly on the command line (e.g., `qm guest passwd 101 root mypass`) can expose the password in shell history or process listings. Consider omitting the password argument if interactive prompting is desired or using more secure methods.<br>Requires appropriate privileges on the Proxmox host (typically root or a user with `PVEVM.GuestControl` permissions).


title: QEMU GUEST AGENT REQUIREMENT
content:
The success of <b>`qm guest passwd`</b> is entirely dependent on the <b>QEMU Guest Agent (`qemu-ga`)</b> being installed and active within the target guest VM. Without `qemu-ga`, the hypervisor has no means to communicate password change requests to the guest operating system. Ensure the guest agent is enabled in the VM's hardware settings in Proxmox to utilize this feature.


title: SECURITY CONSIDERATIONS
content:
When providing the new password directly as an argument to <b>`qm guest passwd`</b>, be mindful of command line history and process visibility. For increased security, consider omitting the password argument and allowing the command to prompt for it interactively if your environment supports it, or use secure shell practices to avoid exposing sensitive information in plain text logs or history files.


title: HISTORY
content:
The `qm guest passwd` functionality was introduced as part of the QEMU Guest Agent integration into <b>Proxmox VE</b>. It evolved to provide more robust guest management capabilities, particularly useful for automation and recovery scenarios in virtualized environments. Its development aligns with Proxmox's goal of offering comprehensive VM lifecycle management capabilities through its command-line interface.


title: SEE ALSO
content:
qm(1): The primary command-line tool for managing virtual machines and containers in Proxmox VE. The `guest` subcommand is part of `qm`., qemu-ga(8): The QEMU Guest Agent daemon, which runs inside the guest VM and facilitates communication with the hypervisor., passwd(1): The standard Linux command used by users to change their own password within a guest OS.


title: PARAMETERS
content:
<b>vmid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><I>Mandatory.</I></b> The unique ID of the virtual machine to which the disk will be imported.<br><br><b>source</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><I>Mandatory.</I></b> The full path to the source disk image file (e.g., <code>/path/to/myvm.qcow2</code>).<br><br><b>storage</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><I>Mandatory.</I></b> The ID of the Proxmox storage backend (e.g., <code>local-lvm</code>, <code>cephfs</code>, <code>nfs_data</code>) where the new virtual disk will be created.<br><br><b>--format <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target disk format for the imported image. Common values include <code>raw</code>, <code>qcow2</code>, or <code>vmdk</code>. If omitted, Proxmox attempts to auto-detect or uses a default based on the storage type.<br><br><b>--sparse <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <code>1</code>, the imported disk will be created as a sparse file on file-based storage, occupying only the space used by data. Set to <code>0</code> for a pre-allocated disk.<br><br><b>--discard <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable or disable TRIM/DISCARD support (<code>1</code> for enabled, <code>0</code> for disabled). Recommended for SSDs or thin-provisioned storage to reclaim unused blocks.<br><br><b>--cache <mode></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the caching mode for the disk. Options include <code>none</code> (default), <code>writethrough</code>, <code>writeback</code>, <code>directsync</code>, and <code>unsafe</code>. Choose based on performance and data integrity requirements.<br><br><b>--aio <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Asynchronous I/O (AIO) mode. Options like <code>native</code>, <code>threads</code>, or <code>io_uring</code> (newer kernels) can affect disk performance.<br><br><b>--size <size></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the target size of the imported disk (e.g., <code>100G</code>, <code>500M</code>). This is useful when the source image is sparse or needs to be resized.<br><br><b>--id <disk_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the controller type and index for the new disk (e.g., <code>scsi0</code>, <code>sata1</code>, <code>ide0</code>). If not provided, Proxmox will assign the next available ID.<br><br>


title: DESCRIPTION
content:
<code>qm import-disk</code> is a Proxmox VE (PVE) command-line utility designed to import an existing disk image file into a specified virtual machine (VM) within the Proxmox environment. This command is essential for scenarios such as migrating VMs from other virtualization platforms (like VMware, VirtualBox, KVM, etc.), importing pre-configured virtual disk images, or attaching new disk images to existing VMs. <br><br>It handles the conversion and placement of the disk image onto Proxmox's various storage types, including LVM, ZFS, directory-based storage, or shared storage like Ceph. The command automates the process of creating a new virtual disk for the VM and copying the data from the source image, offering options to specify the target storage, disk format, and even configure the disk's properties within the VM's configuration. This simplifies the often complex task of bringing external disk data into a Proxmox VM.


title: CAVEATS
content:
Importing large disk images can be time-consuming, depending on the source file size, target storage performance, and chosen format conversion. <br>The command requires direct access to the source disk image file from the Proxmox host. Ensure adequate free space on the target Proxmox storage before starting the import. <br>While <code>qm import-disk</code> attaches the new virtual disk to the VM's configuration, the VM typically needs to be stopped and restarted or rebooted for the operating system within the VM to recognize and utilize the newly imported disk.


title: DISK ATTACHMENT AND CONFIGURATION
content:
Upon successful import, <code>qm import-disk</code> automatically adds the newly created virtual disk to the specified VM's configuration. It will attempt to use the next available virtual slot (e.g., <code>scsi0</code>, <code>sata0</code>) unless explicitly specified with the <code>--id</code> parameter. The disk will be visible in the VM's hardware configuration within the Proxmox GUI or via <code>qm config &lt;vmid&gt;</code>.


title: PERFORMANCE CONSIDERATIONS
content:
The import process can be I/O intensive. Factors affecting performance include the speed of the source disk, the network bandwidth (if the source is network-mounted), and especially the throughput of the target Proxmox storage. Using fast storage like NVMe or Ceph can significantly reduce import times.


title: HISTORY
content:
Proxmox VE, a popular open-source virtualization platform, integrates <code>qm import-disk</code> as a crucial subcommand of its primary VM management utility, <code>qm</code>. This functionality has been available since early versions of Proxmox VE, evolving alongside the platform's growth and its underlying QEMU/KVM virtualization technologies. It became indispensable for system administrators migrating virtual machines from other hypervisors or deploying custom disk images into the Proxmox environment, reflecting the increasing need for flexible VM and storage management in cloud and enterprise setups.


title: SYNOPSIS
content:
<b>qm importdisk</b> &lt;<i>vmid</i>&gt; &lt;<i>source_file</i>&gt; &lt;<i>target_storage</i>&gt; [<i>OPTIONS</i>]


title: PARAMETERS
content:
<b>&lt;<i>vmid</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ID of the virtual machine to which the disk will be imported/attached.<br><br><b>&lt;<i>source_file</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The absolute path to the external disk image file (e.g., <i>.raw</i>, <i>.qcow2</i>, <i>.vmdk</i>) on the Proxmox host.<br><br><b>&lt;<i>target_storage</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ID of the Proxmox storage where the new virtual disk will be created (e.g., <i>local-lvm</i>, <i>local-zfs</i>, <i>NFS-storage</i>).<br><br><b><b>--format</b> &lt;<i>fmt</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the format of the source disk image. Supported formats include <i>raw</i>, <i>qcow2</i>, and <i>vmdk</i>. If omitted, `qm-importdisk` attempts to auto-detect the format.<br><br><b><b>--sparse</b> &lt;<i>boolean</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set to <i>true</i> to create a sparse image on filesystems that support it (e.g., ZFS, Ext4). This means only used blocks are allocated, saving space. Defaults to <i>false</i>.<br><br><b><b>--discard</b> &lt;<i>boolean</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable or disable TRIM/discard support for the virtual disk. Set to <i>true</i> to allow the guest OS to issue TRIM commands to the underlying storage. Defaults to <i>false</i>.<br><br><b><b>--bwlimit</b> &lt;<i>integer</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a bandwidth limit for the import operation, in KiB/s. Useful to prevent the import from saturating network or disk I/O during large transfers.<br><br><b><b>--skip-check</b> &lt;<i>boolean</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set to <i>true</i> to skip the disk format consistency check. Use with caution, as it may lead to corrupted disks if the source file is malformed. Defaults to <i>false</i>.<br><br><b><b>--target-disk</b> &lt;<i>string</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the filename or volume ID for the new disk on the target storage. Useful for custom naming, otherwise Proxmox generates a name.<br><br><b><b>--vm-disk</b> &lt;<i>string</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Directly attach the imported disk to the VM using a specific bus and ID, e.g., <i>scsi0</i>, <i>ide2</i>, <i>virtio0</i>. If this option is not specified, the disk will be created as an 'unused disk' and must be attached manually later using <b>qm set</b>.<br><br>


title: DESCRIPTION
content:
The `qm-importdisk` command, a subcommand of Proxmox VE's primary `qm` utility, facilitates the seamless import of an existing disk image file into a Proxmox virtual machine. This command is crucial for scenarios such as migrating VMs from other hypervisors, adding pre-existing data disks, or converting external disk images into a format suitable for Proxmox. <br><br>It takes a source disk image file (e.g., raw, qcow2, vmdk) and copies its content to a specified Proxmox storage, creating a new virtual disk. Optionally, it can also attach this newly created disk directly to a virtual machine's configuration using a specific bus type (e.g., SCSI, VirtIO, IDE) and disk ID. If not attached directly, the disk will be available as an 'unused' disk within the VM's storage settings, requiring manual attachment later. `qm-importdisk` streamlines the process of integrating external storage resources into the Proxmox ecosystem, making it a fundamental tool for managing VM storage.


title: CAVEATS
content:
Ensure the <i>source_file</i> is accessible by the Proxmox host and that <i>target_storage</i> has sufficient free space for the imported disk. <br>If <b>--vm-disk</b> is not used, the imported disk will be added to the VM's hardware list as an 'unused disk' and will require a manual <b>qm set</b> command to attach it. <br>Disk format auto-detection is generally reliable, but explicitly specifying <b>--format</b> can prevent issues. <br>This command imports the raw disk image; it does not modify or partition the guest's filesystem.


title: USAGE EXAMPLES
content:
Here are some common ways to use <b>qm-importdisk</b>:<br><br><i>Import a QCOW2 image as an unused disk:</i><br><b>qm importdisk 100 /path/to/image.qcow2 local-lvm --format qcow2</b><br><br><i>Import a RAW image and attach it as VirtIO disk 0:</i><br><b>qm importdisk 101 /mnt/backup/data.raw zfs-storage --format raw --vm-disk virtio0 --sparse true</b><br><br><i>Import a VMDK disk with a bandwidth limit:</i><br><b>qm importdisk 102 /var/lib/vmware/myvm.vmdk nfs-share --format vmdk --bwlimit 50000</b> (50MB/s)


title: DISK FORMATS
content:
<b>raw</b>: A bit-for-bit copy of the disk. Simple but does not support advanced features like snapshots directly.<br><b>qcow2</b>: QEMU Copy-On-Write format. Supports snapshots, compression, and thin provisioning. Very common in QEMU/KVM environments.<br><b>vmdk</b>: VMware Virtual Machine Disk format. Used for compatibility with VMware images, allowing easier migration from VMware platforms.


title: HISTORY
content:
The <b>qm-importdisk</b> command is an integral part of the Proxmox VE (Virtual Environment) management toolkit, which has been under continuous development since its inception. It was introduced to simplify the process of bringing external disk images, often from other virtualization platforms or backups, into the Proxmox environment. Over time, its capabilities have expanded, notably with the addition of options like <b>--vm-disk</b> to allow direct attachment during import, significantly streamlining workflows for administrators. Its evolution reflects Proxmox's commitment to providing robust and user-friendly VM management features.


title: SYNOPSIS
content:
<B>qm-list</B><br><I>(Note: This command typically does not accept command-line options or arguments.)</I>


title: DESCRIPTION
content:
<I>qm-list</I> is a utility program provided as part of the <I>Qmail</I> Mail Transfer Agent (MTA) suite. It is designed to display a comprehensive list of messages currently residing within the <I>Qmail</I> mail queue. The command provides an overview of pending outgoing or incoming mail, typically showing details such as the message ID, the sender's address, the recipient's address(es), the message size, and the age of the message in the queue. This tool is invaluable for system administrators to monitor the health and activity of their <I>Qmail</I> mail server, identify potential mail delivery issues, or check for backlogs in the mail queue. It reads directly from the <I>Qmail</I> queue directory structure to compile its report, offering a snapshot of current mail flow.


title: CAVEATS
content:
<ul><li>Requires a functional <I>Qmail</I> installation to be present on the system.</li><li>The command's output format can be complex and may vary slightly depending on the <I>Qmail</I> version or specific patches applied.</li><li>Administrator privileges (root or specific <I>Qmail</I> user) are often required to execute this command successfully, as it needs read access to the <I>Qmail</I> queue directories.</li><li>High queue volumes can result in very lengthy output, potentially difficult to parse manually without piping to other commands.</li></ul>


title: OUTPUT FORMAT
content:
The output of <I>qm-list</I> typically displays messages in a structured format, often including columns for:<br><ul><li><b>Message ID:</b> A unique identifier for the message within the queue.</li><li><b>Sender Address:</b> The email address of the message's originator.</li><li><b>Recipient Addresses:</b> The email addresses of the intended recipients (may be truncated or listed across multiple lines).</li><li><b>Size:</b> The size of the message in bytes.</li><li><b>Age:</b> The duration the message has been in the queue (e.g., 'X days, Y hours').</li><li><b>Status/Reason:</b> Information indicating if the message is temporarily undeliverable or delayed, often with an associated error message.</li></ul>


title: TYPICAL USAGE
content:
Administrators frequently pipe the output of <I>qm-list</I> to other standard Unix commands like <I>grep</I>, <I>awk</I>, or <I>less</I> for filtering, further processing, or easier viewing, especially when dealing with large queues. For instance, <B>qm-list | grep 'user@example.com'</B> could be used to find messages destined for a specific user, or <B>qm-list | less</B> for paginated viewing.


title: HISTORY
content:
<I>Qmail</I> itself was originally developed by Daniel J. Bernstein (DJB) in 1995, with a strong emphasis on security, reliability, and simplicity. <I>qm-list</I> emerged as one of the essential utility programs within the <I>Qmail</I> suite, providing administrators with a crucial tool for queue management and monitoring. Unlike many other MTA utilities that might evolve with numerous command-line options, <I>qm-list</I> has largely maintained its simple, direct functionality, reflecting <I>Qmail's</I> overall design philosophy of doing one thing well. Its usage became widespread in environments utilizing <I>Qmail</I> as their primary mail server.


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique integer ID of the virtual machine (VM) for which to list snapshots. This is a mandatory argument.<br><br><b><b>--full</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When set to '1' (true), this option displays full snapshot properties, including creation time (<i>snaptime</i>), parent snapshot (<i>parent</i>), and virtual machine state at the time of the snapshot (<i>vmstate</i>). Default is '0' (false).<br><br><b><b>--output-format</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format of the listed snapshots. Supported formats include 'json', 'prettyjson', 'yaml', 'html', 'xml', 'tsv', 'csv', and 'text'.<br><br><b><b>--output-options</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Additional options specific to the chosen output format, typically used for column selection or formatting details.<br><br><b><b>--quiet</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to '1' (true), suppresses informational messages and warnings, printing only the core output. Default is '0' (false).<br><br><b><b>--verbose</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to '1' (true), enables verbose output, providing more detailed status information during execution. Default is '0' (false).<br><br>


title: DESCRIPTION
content:
The <b>qm-listsnapshot</b> command is a subcommand of Proxmox VE's primary virtual machine management tool, <b>qm</b>. It is specifically designed to display a list of all existing snapshots associated with a given QEMU/KVM virtual machine. <br><br>When executed, it provides an overview of each snapshot, typically showing its name, a short description, and its state (e.g., 'running' or 'stopped' if the VM was running when the snapshot was taken). Using the <b>--full</b> option, users can retrieve more detailed information, such as the exact time the snapshot was created, its parent snapshot in the history tree, and potentially the disk space consumed by the snapshot. <br><br>This command is crucial for administrators to monitor and manage the rollback points of their virtual machines, helping them to identify available recovery states before performing operations like rollback or deletion.


title: CAVEATS
content:
It's important to understand that snapshots are not full backups. While they provide a quick rollback point, they are dependent on the underlying VM disk image and are not suitable for long-term archival or disaster recovery across different systems. <br><br>The <b>qm-listsnapshot</b> command is specifically for QEMU/KVM virtual machines managed by Proxmox VE; for LXC containers, a similar command like <b>pct listsnapshot</b> would be used.


title: OUTPUT COLUMNS
content:
When running <b>qm-listsnapshot</b> without the <b>--full</b> option, the output typically includes the following columns: <br><i><b>Name</b></i>: The name given to the snapshot.<br><i><b>Description</b></i>: A user-defined description for the snapshot.<br><i><b>VMState</b></i>: The state of the VM (e.g., 'running', 'stopped') when the snapshot was taken.<br><br>With the <b>--full</b> option, additional columns may be displayed: <br><i><b>SnapTime</b></i>: The exact date and time the snapshot was created.<br><i><b>Parent</b></i>: The name of the parent snapshot, indicating its position in the snapshot tree.<br><i><b>DiskSize</b></i>: The size of the disk delta introduced by the snapshot.


title: EXAMPLE USAGE
content:
To list all snapshots for a VM with ID 101:<br><code>qm listsnapshot 101</code><br><br>To list full details of snapshots for VM 101:<br><code>qm listsnapshot 101 --full</code><br><br>To list snapshots for VM 101 and output in JSON format:<br><code>qm listsnapshot 101 --output-format json</code>


title: HISTORY
content:
The <b>qm</b> command-line utility, including its snapshot management subcommands like <b>listsnapshot</b>, has been a fundamental component of Proxmox VE since its early versions. As Proxmox VE evolved, features related to snapshots, such as live snapshots and improved integration with various storage backends, have been introduced and refined, making <b>qm-listsnapshot</b> a more robust and informative tool over time.


title: PARAMETERS
content:
<b>&lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID of the virtual machine to migrate.<br><br><b>&lt;target&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the target Proxmox VE node.<br><br><b>--bwlimit &lt;integer&gt; (MB/s)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum bandwidth limit for the migration process in megabytes per second. Useful for controlling network load.<br><br><b>--compress &lt;string&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the compression algorithm to use for migration data. Default is 'zstd'. Other options may include 'none'.<br><br><b>--cpu &lt;string&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the migration to use a specified CPU type on the target. Only valid with '--live' migration. Useful for managing CPU compatibility.<br><br><b>--dry-run &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to 'true', the command only checks if the migration is possible and reports any issues, without actually performing the migration.<br><br><b>--force &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the migration to proceed even if the VM is locked or other checks fail. Use with caution.<br><br><b>--iface &lt;string&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the network interface to use for migration traffic on the source node. Useful for dedicated migration networks.<br><br><b>--live &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to 'true', performs a live migration, meaning the VM remains running during the process with minimal downtime. Requires shared storage for disks by default.<br><br><b>--migrate-downtime &lt;integer&gt; (ms)</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum allowed downtime for live migration in milliseconds. Default is usually 150ms.<br><br><b>--migration-type &lt;string&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the security type of the migration. Options are 'secure' (default, uses SSH) or 'insecure' (plaintext connection).<br><br><b>--nocompress &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables ZSTD compression during migration. Can be useful in high-bandwidth, low-CPU scenarios.<br><br><b>--online &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deprecated. Use '--live' instead. Performs an online migration.<br><br><b>--shared-storage &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assumes that shared storage is used for the VM's disks. This allows live migration without transferring disk data.<br><br><b>--skip-shared-storage &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When doing online migration and source/target storage are shared, this option attempts to skip the storage live migration setup.<br><br><b>--target-bridge &lt;string&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a different network bridge to use on the target node for the VM's network interfaces.<br><br><b>--target-storage &lt;string&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a mapping from source storage to target storage for VM disks. Format: &lt;source_storage&gt;:&lt;target_storage&gt;[,...]. Essential when migrating VMs with local disks.<br><br><b>--with-local-disks &lt;boolean&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to 'true', enables migration of VMs with local disks. This implicitly triggers an offline migration, as disk data must be transferred.<br><br>


title: DESCRIPTION
content:
The <b>qm migrate</b> command facilitates the movement of a QEMU/KVM virtual machine (VM) from its current Proxmox VE host to a different node within the same Proxmox cluster. This operation can be performed as a <I>live migration</I>, where the VM continues to run with minimal interruption, or an <I>offline migration</I>, which requires the VM to be stopped. Live migration is generally preferred for critical services but typically requires shared storage for VM disks, or relies on storage migration if disks are local. The command efficiently handles the transfer of VM state, memory, and disk images, ensuring continuity or controlled downtime based on the chosen method and storage configuration.


title: CAVEATS
content:
Live migration (<I>--live</I>) typically requires shared storage for VM disks. If local disks are present and not shared, the <I>--with-local-disks</I> option must be used, which will force an offline migration (VM downtime).<br>Ensure sufficient network bandwidth and proper network configuration between source and target nodes, especially for large VMs or live migrations. Consider using a dedicated migration network via the <I>--iface</I> option.<br>CPU compatibility between source and target nodes is crucial for live migration. If CPUs are not compatible, an offline migration might be necessary, or the <I>--cpu</I> option can be used to set a compatible CPU type.<br>The <I>--force</I> option should be used with extreme care as it can override critical safety checks.


title: MIGRATION TYPES EXPLAINED
content:
Proxmox VE offers two primary migration types: <I>Live Migration</I> and <I>Offline Migration</I>.<br><br><B>Live Migration</B> (<I>--live</I>): The VM remains running during the migration process, resulting in minimal or no perceived downtime for users. This is ideal for critical services. It typically requires the VM's disk images to be stored on shared storage accessible by both source and target nodes, or for Proxmox to perform a storage live migration if local disks are involved. Memory and VM state are transferred incrementally.<br><br><B>Offline Migration</B> (<I>--with-local-disks</I>): The VM is stopped on the source node before the migration begins and is only restarted on the target node once all data transfer is complete. This method is necessary when disks are local to the source node and no shared storage is available, or when the live migration prerequisites cannot be met. It incurs noticeable downtime.


title: STORAGE CONSIDERATIONS
content:
The storage configuration of your VM's disks significantly impacts migration capabilities:<br><br>If VM disks reside on <B>shared storage</B> (e.g., NFS, iSCSI, Ceph), live migration is straightforward as only the VM's memory and state need to be transferred; the disk data remains accessible to the new host. Use <I>--shared-storage</I> if disks are on shared storage.<br><br>If VM disks are stored on <B>local storage</B> (e.g., ZFS, LVM on a node's local disks), a live migration is still possible, but it requires the disk data to be transferred alongside the memory and state. This is achieved via a storage live migration. Alternatively, using <I>--with-local-disks</I> forces an offline migration, where disks are copied to the target node's local storage or specified <I>--target-storage</I>.


title: HISTORY
content:
The <I>qm migrate</I> command is a fundamental component of Proxmox VE, designed to enable high availability and flexible resource management within clusters. It has been a core feature since the early iterations of Proxmox VE, continuously evolving with advancements in QEMU/KVM and cluster technologies. Subsequent Proxmox VE versions have introduced enhancements, such as improved live migration capabilities, better handling of local storage migration, and additional options for fine-tuning performance and security.


title: SYNOPSIS
content:
<code>steamos-boot-install [OPTIONS] --mountpoint &lt;path&gt; --boot-partition &lt;path&gt; --root-partition &lt;path&gt;</code> <br><i>(Commonly used flags; not exhaustive. Typically called by installer scripts.)</i>


title: PARAMETERS
content:
<b><code>--mountpoint &lt;path&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the mount point of the root filesystem where SteamOS is installed (e.g., <code>/mnt</code>).<br><br><b><code>--boot-partition &lt;path&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the EFI System Partition (ESP) or the dedicated boot partition (e.g., <code>/dev/nvme0n1p1</code>).<br><br><b><code>--root-partition &lt;path&gt;</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the root filesystem partition of the SteamOS installation (e.g., <code>/dev/nvme0n1p3</code>).<br><br><b><code>--efi</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly indicates an EFI (UEFI) boot environment for bootloader installation.<br><br><b><code>--systemd-boot</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the installer to use <i>systemd-boot</i> as the bootloader, which is common on the Steam Deck.<br><br><b><code>--grub</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the installer to use <i>GRUB</i> as the bootloader (often for older SteamOS versions or specific PC setups).<br><br><b><code>--force</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the installation process, potentially overwriting existing boot entries or configurations.<br><br><b><code>--verbose</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides more detailed output during the installation process, useful for monitoring.<br><br><b><code>--debug</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables even more verbose debug output for in-depth troubleshooting.<br><br><b><code>--preserve-dual-boot</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to preserve existing boot entries if a dual-boot setup is detected during installation.<br><br><b><code>--install-efi-entries</code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly ensures that EFI boot entries are installed or updated in the system's firmware.<br><br>


title: DESCRIPTION
content:
<code>steamos-boot-install</code> is a crucial internal utility used primarily during the installation or recovery of Valve's SteamOS operating system. Its primary function is to configure and install the appropriate bootloader (either GRUB or systemd-boot, depending on the system and configuration) to ensure SteamOS can successfully boot. This command handles the complexities of setting up EFI boot entries on modern systems or traditional MBR boot records on older BIOS-based machines. It integrates with the system's existing boot infrastructure, managing boot partitions, and ensuring the correct kernel and initramfs are loaded. While typically invoked automatically by the SteamOS installer, its underlying logic addresses various boot scenarios, including single-boot installations, updates to existing installations, and sometimes even complex dual-boot setups by interacting with <code>efibootmgr</code> or <code>grub-install</code> utilities. It ensures that SteamOS is properly registered as a bootable entry.


title: CAVEATS
content:
This command is an internal utility primarily used by the SteamOS installer scripts. It is generally not intended for direct manual invocation by end-users unless specifically instructed for recovery or advanced troubleshooting scenarios. Incorrect usage can lead to an unbootable system. Its behavior and available options may vary significantly between different SteamOS versions and specific hardware platforms (e.g., Steam Deck vs. generic PC installations).


title: CONTEXT IN STEAMOS INSTALLATION
content:
During a typical SteamOS installation or reinstallation, after the system's partitions are created and the root filesystem populated, <code>steamos-boot-install</code> is invoked as one of the final steps. Its role is to ensure that the newly installed SteamOS system can be properly discovered and booted by the system's firmware or an existing boot manager, making the system operational.


title: STEAM DECK SPECIFICS
content:
On the Steam Deck, <code>steamos-boot-install</code> heavily leverages <code>systemd-boot</code> due to its simplicity and direct UEFI integration, which is a key difference from older SteamOS versions that relied more on GRUB. This command is vital for setting up the A/B partition scheme's boot logic, enabling seamless and robust system updates and rollbacks specific to the Steam Deck's design.


title: HISTORY
content:
<code>steamos-boot-install</code> is a specialized component of Valve's custom SteamOS installer. Its development is intrinsically linked to the evolution of SteamOS itself, from its initial Debian-based PC releases to the modern Arch Linux-based Steam Deck. The command's underlying logic has adapted over time to support various bootloaders (e.g., the transition from primarily GRUB to `systemd-boot` for the Steam Deck) and different hardware boot environments (BIOS vs. UEFI). It represents a critical piece of Valve's efforts to streamline the boot configuration aspect of their Linux-based gaming operating system.


title: SYNOPSIS
content:
<b>steamos-finalize-install</b><br><i>(This is an internal script usually invoked by the SteamOS installer; no common user-facing options or arguments are typically used.)</i>


title: DESCRIPTION
content:
<i>steamos-finalize-install</i> is a crucial internal script executed during the final stages of a SteamOS installation. Its primary purpose is to perform essential post-installation configurations, ensuring the system is ready for its first boot and optimal performance. This includes tasks such as setting up user accounts (e.g., <b>steam</b> user), configuring system services, installing proprietary drivers, applying necessary system patches, setting up the <b>steam</b> user's home directory, and integrating Steam Big Picture mode as the primary desktop experience.<br><br>It's typically invoked automatically by the SteamOS installer or recovery process, rather than being run directly by an end-user with command-line arguments. It acts as the bridge between a raw system installation and a fully functional SteamOS gaming environment, often ensuring proper filesystem setup and security hardening.


title: CAVEATS
content:
This is an <i>internal SteamOS script</i>, not intended for direct manual execution by general users outside of specific debugging or development scenarios. Incorrect manual execution could lead to an unstable or unbootable system. Its behavior is highly dependent on the SteamOS version and installation context. It's usually invoked by the official installer or recovery system as a critical part of the automated setup.


title: AUTOMATION ROLE
content:
This script is central to the automated, hands-off installation experience SteamOS aims for, handling complex system configurations transparently without requiring manual intervention from the user.


title: EXECUTION CONTEXT
content:
It is almost exclusively run within the installer environment or during a system recovery process, typically as a <b>post-install</b> hook or a final setup step before the first boot into the SteamOS desktop environment.


title: HISTORY
content:
<i>steamos-finalize-install</i> was introduced as a core component of the SteamOS installation process. Its development has focused on automating the complex setup of the custom SteamOS environment, evolving with different SteamOS versions (e.g., from Debian-based SteamOS 2 to Arch-based SteamOS 3). It plays a key role in ensuring a seamless and automated user experience for setting up a gaming-centric Linux distribution.


title: TLDR
content:
<b>Finalize the installation</b>`sudo steamos-finalize-install`<br><b>Finalize without updating bootloaders or kernel</b>`sudo steamos-finalize-install --no-bootloaders --no-kernel`<br><b>Skip all migration steps</b>`sudo steamos-finalize-install --no-migrate`<br><b>Set a specific root hash during finalization</b>`sudo steamos-finalize-install --roothash [hash]`<br><b>Force system migration steps regardless of environment</b>`sudo steamos-finalize-install --force`


title: PARAMETERS
content:
<b>enable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates <i>Developer Mode</i>, unlocking advanced system features like SSH access and root filesystem write capabilities. This action typically requires a reboot for changes to take full effect.<br><br><b>disable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deactivates <i>Developer Mode</i>, reverting the system to its default, more secure, and locked-down state. This action also typically requires a reboot.<br><br>


title: DESCRIPTION
content:
The <b>steamos-devmode</b> command is a specialized utility designed for SteamOS, particularly prominent on devices like the Steam Deck. Its primary function is to toggle the system's "Developer Mode" on or off. When <i>Developer Mode</i> is enabled, it unlocks critical functionalities essential for advanced users, system administrators, and developers. These functionalities often include enabling SSH access to the device, allowing modifications to the otherwise read-only root filesystem, and potentially granting more granular control over various system services and settings. <br><br>This command abstracts the complex underlying system changes required to switch between these states. It's indispensable for users looking to install non-Steam software, debug system issues, perform deep system customizations, or experiment with the device's Linux environment beyond the standard gaming interface. Conversely, disabling Developer Mode reverts the system to its default, more secure, and locked-down state, which is typical for a consumer-oriented gaming device. It helps maintain system integrity and prevents accidental or malicious modifications by average users.


title: CAVEATS
content:
Enabling <i>Developer Mode</i> significantly reduces the system's default security posture and can expose it to potential vulnerabilities. Modifying the root filesystem, while allowed in developer mode, can lead to system instability, prevent future system updates, or even brick the device if done improperly. Use with caution and only if you understand the implications of system-level modifications.


title: SECURITY IMPLICATIONS
content:
Activating <i>Developer Mode</i> removes several layers of security intended for a consumer device. This includes potentially exposing services like SSH to the network and allowing unrestricted modifications to critical system files. It is strongly advised to use this mode only when necessary and to understand the associated risks.


title: ROOT FILESYSTEM
content:
One of the key features unlocked by <i>Developer Mode</i> is the ability to remount the root filesystem as writable. SteamOS normally uses an immutable root filesystem (A/B partitioning with read-only root) to ensure system stability and seamless updates. Modifying this can interfere with Valve's update mechanism and potentially lead to an unbootable system if not handled carefully.


title: REBOOT REQUIREMENT
content:
Both enabling and disabling <i>Developer Mode</i> typically require a system reboot for the changes to take full effect. The command will often prompt the user to confirm the reboot or perform it automatically after executing the desired action.


title: HISTORY
content:
The <b>steamos-devmode</b> utility became particularly relevant and widely used with the advent of the Steam Deck. As a portable gaming PC running a specialized version of Arch Linux (SteamOS), the Steam Deck's operating system is designed for robustness and ease of updates, utilizing an immutable root filesystem. For users and developers who wished to extend the device's capabilities beyond its intended gaming purpose, enabling developer mode became a crucial first step. Its introduction facilitated a vibrant community around customization, emulation, and software development for the Steam Deck, allowing users to unlock the full potential of the underlying Linux system.


title: TLDR
content:
<b>Enable developer mode</b>`sudo steamos-devmode enable`<br><b>Enable developer mode without confirmation prompt</b>`sudo steamos-devmode enable --no-prompt`<br><b>Check if developer mode is currently enabled</b>`sudo steamos-devmode status`


title: PARAMETERS
content:
<b>-o <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the local output filename. If not given, the filename is derived from the URL.<br><br><b>-u <URL></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a base URL to find the target file, especially if the <i>.zsync</i> file is local.<br><br><b>-i</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs zsync to only check the existing file and generate a <i>.zsync</i> file for it, without downloading.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to -i, used for scanning local files to generate <i>.zsync</i> data.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs in quiet mode, suppressing non-essential output.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs in verbose mode, providing more detailed output.<br><br><b>-k</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keeps any partial files on error, allowing for manual inspection or later resumption.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resumes an incomplete download, continuing from where it left off.<br><br><b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces download even if the local file appears to be identical to the remote.<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Don't download; instead, output the URL of the <i>.zsync</i> file that would be used.<br><br><b>-H <header></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a custom HTTP header to requests (e.g., <i>User-Agent: myapp/1.0</i>).<br><br><b>-A <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the HTTP User-Agent string for requests.<br><br><b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables batch mode, suitable for scripting.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<i>zsync</i> is a file transfer program that allows for efficient downloading of files, especially when a previous version or part of the file already exists locally. It operates similarly to <i>rsync</i> by employing the same delta-transfer algorithm, which intelligently identifies and transfers only the changed blocks or differences between the local file and the remote target file. This significantly reduces the amount of data transferred, making it highly bandwidth-efficient and faster for updates to large files. <br><br>Unlike <i>rsync</i>, which is a general-purpose synchronization tool often used for server-to-server transfers, <i>zsync</i> is specifically designed for one-way downloads from HTTP/HTTPS web servers or local file paths. It requires a small <i>.zsync</i> control file, which contains checksums and block information about the target file, to be available alongside the file on the server. <i>zsync</i> uses this control file to determine which blocks of the local file need updating, then requests only those specific ranges from the web server using HTTP range requests. This makes <i>zsync</i> ideal for distributing software updates, large datasets, or any files where minor changes are frequent and users might have an older version.


title: CAVEATS
content:
<ul><li>Requires a pre-generated <i>.zsync</i> control file (e.g., <i>filename.zsync</i>) to be present and accessible alongside the target file on the server.</li><li>The web server serving the target file must support HTTP Range Requests, which allows <i>zsync</i> to download only specific parts of the file.</li><li><i>zsync</i> is a one-way download utility, not a bidirectional synchronization tool like <i>rsync</i>.</li><li>For very small files or entirely new files, the overhead of checking checksums might make <i>zsync</i> slightly slower than a direct full download with tools like <i>wget</i> or <i>curl</i>.</li></ul>


title: GENERATING .ZSYNC FILES
content:
To use <i>zsync</i>, a <i>.zsync</i> control file must first be created from the target file. This is typically done using the <i>zsyncmake</i> utility (often packaged with <i>zsync</i>). For example, <i>zsyncmake largefile.iso</i> would create <i>largefile.iso.zsync</i>. This <i>.zsync</i> file then needs to be made available on the web server alongside <i>largefile.iso</i>.


title: SERVER REQUIREMENTS
content:
For <i>zsync</i> to function correctly, the web server hosting the target file must support HTTP Range Requests (RFC 7233). This feature allows <i>zsync</i> to request only specific byte ranges of the file, which is crucial for its delta-transfer mechanism. Most modern web servers (e.g., Apache, Nginx) support this by default.


title: HISTORY
content:
<i>zsync</i> was developed by Colin Phipps, inspired by the efficiency of the <i>rsync</i> algorithm. Its primary goal was to adapt this powerful delta-transfer mechanism for use over HTTP, enabling bandwidth-efficient file updates from standard web servers. It gained some traction in projects requiring efficient distribution of large files, such as Linux distribution ISO updates or game patches, where users often have an older version of the file locally. While not as widely known as <i>rsync</i>, it fills a specific niche for efficient web-based downloads requiring partial file updates.


title: TLDR
content:
<b>Download a file using a .zsync control file</b>`zsync [path/to/url.zsync]`<br><b>Use a local file as a seed to avoid re-downloading unchanged parts</b>`zsync -i [path/to/existing_file] [path/to/url.zsync]`<br><b>Save the updated file under a specific name</b>`zsync -i [path/to/existing_file] -o [path/to/new_file] [path/to/url.zsync]`<br><b>Resume a partial download and keep the temporary file</b>`zsync -k [path/to/url.zsync]`<br><b>Run in quiet mode with minimal output (no progress bar, download rate, or ETA display)</b>`zsync -q [path/to/url.zsync]`


title: SYNOPSIS
content:
Not applicable. The command <I>oniux</I> is not recognized as a standard Linux utility, therefore no general syntax or usage pattern can be provided.


title: DESCRIPTION
content:
The command <I>oniux</I> does not appear to be a standard, commonly recognized, or pre-installed utility within typical Linux distributions. It is highly probable that the command name contains a typo, or it might refer to a very specific custom script, an alias configured in a user's shell environment, or a highly specialized, less common third-party utility. As <I>oniux</I> is not part of the core GNU/Linux utilities or widely known packages, detailed information regarding its functionality, typical syntax, command-line options, or common use cases cannot be provided. Users encountering this command should verify its source, check for potential misspellings, or consult local system documentation if it's a custom tool specific to their environment.


title: CAVEATS
content:
This command is not recognized as a standard Linux utility. It is crucial to verify the spelling. If you intended to refer to a different command, please correct the name. If <I>oniux</I> is part of a custom system or a specific application's toolkit, its functionality, usage, and safety would depend entirely on its local implementation and the environment it runs within. Attempting to execute unrecognized commands without understanding their origin can be risky.


title: VERIFICATION
content:
If you believe <I>oniux</I> should be a recognized command, please ensure your system's package repositories are up-to-date and that all necessary packages are installed. You may also check for common misspellings or consult system administrators for custom scripts.


title: HISTORY
content:
No history available as <I>oniux</I> is not a recognized command within standard Linux distributions or historical documentation.


title: TLDR
content:
<b>Isolate an application</b>`oniux [command]`<br><b>Query a website</b>`oniux curl [https://example.com]`<br><b>Query an onion site</b>`oniux curl [http://example.onion]`<br><b>Run an entire shell in "torified" isolation</b>`oniux bash`<br><b>Isolate graphical applications in desktop environments</b>`oniux hexchat`


title: PARAMETERS
content:
<b><b>rw</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remounts the root filesystem in read-write mode. This allows for system-wide modifications.<br><br><b><b>ro</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remounts the root filesystem back to its default read-only mode, which is recommended for daily use and system stability.<br><br>


title: DESCRIPTION
content:
The <i>mount.steamos</i> command is a specialized utility found on Valve's SteamOS, particularly on the Steam Deck. Its primary purpose is to manage the read-only (RO) state of the root filesystem, which is the default configuration on SteamOS 3.0 and newer. This read-only design enhances system stability, simplifies updates, and prevents accidental corruption. <br><br>When users need to make system-wide modifications, install non-Flatpak applications, or perform advanced debugging, <i>mount.steamos</i> allows them to temporarily remount the root filesystem in a read-write (RW) mode. This often involves creating an overlay filesystem (like <i>overlayfs</i>) that captures changes without altering the underlying immutable base.<br><br>After modifications, it's recommended to revert to read-only mode to maintain system integrity and compatibility with future updates.


title: CAVEATS
content:
<i>Requires superuser privileges (typically invoked with <i>sudo</i>).</i><br><i>Modifying the root filesystem can potentially lead to system instability or interfere with future SteamOS updates.</i><br><i>Changes made in read-write mode might not persist across system updates or reboots, depending on the underlying mechanism (e.g., <i>overlayfs</i> might be reset).</i><br><i>Primarily intended for advanced users, developers, or troubleshooting scenarios.</i><br><i>This command is specific to SteamOS 3.0 and later, used on devices like the Steam Deck.</i>


title: PERSISTENCE OF CHANGES
content:
It's crucial to understand that changes made while the root filesystem is in read-write mode using <i>mount.steamos</i> might not be persistent across system updates or even some reboots. SteamOS's <i>ostree</i>-based A/B partition scheme means that system updates often involve switching to a new, clean root filesystem. Any modifications made directly to the active rootfs (even via <i>overlayfs</i>) could be lost during such updates. For persistent changes, users should prefer Flatpaks, package managers like <i>pacman</i> within a <i>chroot</i>, or SteamOS developer tools designed for persistence.


title: UNDERLYING MECHANISM
content:
While <i>mount.steamos</i> abstracts the complexity, its typical implementation involves leveraging Linux kernel features like <i>overlayfs</i>. This creates a writable layer on top of the read-only base filesystem. When files are modified or new ones are created, they are written to the writable overlay, while the original files on the read-only layer remain untouched. This ensures that the base system can always be restored to a known good state.


title: HISTORY
content:
<i>mount.steamos</i> was introduced with SteamOS 3.0, a significant architectural shift that adopted an immutable operating system design based on <i>ostree</i> (similar to Fedora Silverblue or ChromeOS). This change, prominent with the release of the Steam Deck, necessitated a dedicated utility to allow users to temporarily bypass the read-only nature of the root filesystem for development and customization purposes, bridging the gap between an immutable system and traditional Linux modification practices.


title: TLDR
content:
<b>Mount all necessary partitions from a device to a target directory</b>`sudo mount.steamos [/dev/sdX] [/mnt]`<br><b>Mount with options to exclude specific partitions (e.g. /home, overlays)</b>`sudo mount.steamos [[-o|--options]] nohome,nooverlay [/dev/sdX] [/mnt]`<br><b>Unmount all partitions mounted under a target directory</b>`sudo mount.steamos -u [/mnt]`<br><b>Display help</b>`mount.steamos [[-h|--help]]`


title: PARAMETERS
content:
<b>-o <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output PDF file name. If omitted, the output file typically defaults to the input file's name with a `.pdf` extension.<br><br><b>--css <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a custom CSS stylesheet (for HTML intermediates if converted via HTML) or influences the styling of the generated PDF. Note: Direct CSS to PDF conversion is complex; this usually implies intermediate HTML.<br><br><b>--toc</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes a table of contents in the generated PDF.<br><br><b>--standalone</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the output PDF is a complete, self-contained document, often necessary for proper header/footer/TOC generation (corresponds to <i>Pandoc's</i> `-s`).<br><br><b>-V <I>KEY</I>=<I>VALUE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes variables to the underlying template, allowing customization of metadata like title, author, date, or specific <i>LaTeX</i> options.<br><br><b>--template <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom template file to use for rendering the PDF, offering advanced control over the document's structure and appearance.<br><br><b>--highlight-style <I>STYLE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the style for syntax highlighting of code blocks. Common styles include `pygments`, `kate`, `espresso`, `zenburn`, etc.<br><br>


title: DESCRIPTION
content:
The `markdown2pdf` command provides a convenient way to transform plain-text Markdown documents into professional-looking PDF files. While not a standard utility found in all Linux distributions, it typically acts as a wrapper or alias around powerful document conversion tools like <i>Pandoc</i>, leveraging underlying technologies such as <i>LaTeX</i> for high-quality typesetting. Its primary purpose is to automate the often complex process of converting Markdown, which is excellent for writing content quickly, into a universally viewable and printable PDF format.<br><br>Users can leverage `markdown2pdf` to create reports, articles, books, or any document requiring a polished PDF output from their Markdown source. It simplifies the workflow by abstracting away the intricacies of command-line arguments required by its dependencies, making it accessible even for users not familiar with <i>Pandoc</i> or <i>LaTeX</i> directly. This utility is invaluable for developers, writers, and anyone who prefers Markdown for content creation but needs PDF for distribution or printing.


title: CAVEATS
content:
<ul><li>`markdown2pdf` is often a custom script or alias, not a universally installed standard command. Its availability and exact options can vary widely.</li><li>It typically relies on external dependencies like <i>Pandoc</i> and a <i>LaTeX</i> distribution (e.g., <i>TeX Live</i>, <i>MiKTeX</i>) for actual conversion and typesetting. These dependencies must be installed and correctly configured.</li><li>Advanced PDF customization often requires familiarity with <i>LaTeX</i> syntax or <i>Pandoc</i> templates.</li><li>The quality and features of the output PDF are highly dependent on the version and configuration of the underlying tools.</li></ul>


title: INSTALLATION AND DEPENDENCIES
content:
To use a `markdown2pdf` utility, you typically need to install <b>Pandoc</b> and a <b>LaTeX</b> distribution. On Debian/Ubuntu, you might use `sudo apt install pandoc texlive-full`. On macOS, Homebrew can install `pandoc` and <i>MacTeX</i> (a LaTeX distribution). Without these core components, `markdown2pdf` will likely fail to perform the conversion.


title: COMMON WORKFLOW
content:
A typical workflow involves writing your content in a Markdown file (e.g., `document.md`), then running `markdown2pdf document.md -o output.pdf`. For more complex documents, you might specify a custom template or pass variables for metadata like author and title directly from the command line.


title: HISTORY
content:
The concept of converting Markdown to PDF gained traction as Markdown became a popular lightweight markup language for documentation, writing, and blogging. Early solutions often involved multi-step processes, piping Markdown through tools like <i>Pandoc</i> and then into <i>pdflatex</i>. The `markdown2pdf` command, or similar custom scripts, emerged as a user-friendly abstraction to streamline this process, making it a single-command operation. This convenience contributed to its widespread adoption in various developer workflows and academic settings, simplifying the creation of presentable documents from easily editable Markdown sources. It reflects the community's desire for efficient, text-based document creation pipelines.


title: TLDR
content:
<b>Convert a Markdown file to a PDF</b>`markdown2pdf [[-p|--path]] [path/to/input_file.md]`<br><b>Convert a Markdown file to a PDF with a specific path</b>`markdown2pdf [[-p|--path]] [path/to/input_file.md] [[-o|--output]] [path/to/output_file.pdf]`<br><b>Convert Markdown content provided as a string</b>`markdown2pdf [[-s|--string]] [markdown_text] [[-o|--output]] [path/to/output_file.pdf]`<br><b>Convert from URL (this will convert a Markdown file at that URL to a local PDF file)</b>`markdown2pdf [[-u|--url]] [URL] [[-o|--output]] [path/to/output_file.pdf]`


title: TLDR
content:
<b>Flood access points with beacon frames to create fake networks (set interface to monitor mode with sudo airmon-ng start wifi_interface if needed)</b>`sudo mdk4 [wifi_interface] b -f [path/to/beacons.txt]`<br><b>Perform deauthentication attack against all clients on all BSSIDs</b>`sudo mdk4 [wifi_interface] d`<br><b>Perform deauthentication attack on a specific BSSID (list BSSIDs using sudo airodump-ng wifi_interface)</b>`sudo mdk4 [wifi_interface] d -B [BSSID]`


title: PARAMETERS
content:
<b><b>devspace init</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes a new DevSpace project and creates a <code>devspace.yaml</code> configuration file.<br><br><b><b>devspace dev</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the development mode: builds images, deploys the application, and sets up file synchronization, port-forwarding, and log streaming for rapid development.<br><br><b><b>devspace deploy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds images and deploys the application to Kubernetes. Can be used for staging or production deployments.<br><br><b><b>devspace build</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds images defined in <code>devspace.yaml</code> without deploying the application.<br><br><b><b>devspace purge</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes the deployed application, built images, and associated resources from the Kubernetes cluster.<br><br><b><b>devspace enter</b> <I>container</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Connects to a running container via a shell (similar to <code>kubectl exec</code>).<br><br><b><b>devspace logs</b> <I>container</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Streams logs from a running container (similar to <code>kubectl logs</code>).<br><br><b><b>devspace run</b> <I>command</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes a custom script or command defined in <code>devspace.yaml</code> within the development container or locally.<br><br><b><b>devspace update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Updates the DevSpace CLI to the latest version.<br><br><b><b>--kube-context</b> <I>context</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Kubernetes context to use for operations.<br><br><b><b>--namespace</b> <I>namespace</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Kubernetes namespace to use for operations.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows help message for a command or the CLI itself.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the DevSpace CLI version.<br><br>


title: DESCRIPTION
content:
DevSpace is an open-source command-line interface (CLI) tool designed to simplify the development and deployment of applications on Kubernetes. It bridges the gap between local development environments and remote Kubernetes clusters, allowing developers to build, deploy, and debug their applications directly within the cluster without needing to manually manage Dockerfiles, Helm charts, or kubectl commands. <br><br>Key features include: <br><i><b>Fast Iteration Cycles:</b></i> It supports "hot-reloading" or "file synchronization," where local code changes are instantly reflected in the running container within Kubernetes, significantly speeding up development. <br><i><b>Image Building:</b></i> Automates Docker image building and pushing to registries. <br><i><b>Dependency Management:</b></i> Can deploy dependencies like databases or message queues directly into the cluster. <br><i><b>Port-Forwarding & Proxying:</b></i> Automatically sets up port-forwarding for services and containers. <br><i><b>One-Command Deployment:</b></i> Simplifies complex multi-service deployments into a single <code>devspace deploy</code> command. <br><i><b>Integrated Debugging:</b></i> Connects local debuggers to containers running in Kubernetes. <br><i><b>DevSpace.yaml:</b></i> Uses a powerful, declarative configuration file (<code>devspace.yaml</code>) to define the entire development workflow, including image builds, deployments, port-forwards, and sync-paths. <br><br>DevSpace aims to make cloud-native development as seamless and efficient as traditional local development.


title: CAVEATS
content:
DevSpace requires a running Kubernetes cluster and <code>kubectl</code> to be installed and configured. It often relies on Docker or another container runtime for local image building. The <code>devspace.yaml</code> file is central to its operation; misconfigurations can lead to unexpected behavior. Proper network connectivity between the DevSpace CLI host and the Kubernetes API server is crucial for its functionalities.


title: CONFIGURATION FILE: DEVSPACE.YAML
content:
This YAML file is the core of any DevSpace project. It defines how images are built, how applications are deployed (e.g., using Helm charts, manifests), which ports to forward, which files to synchronize, and custom commands or development tools. It enables a highly customizable and declarative development workflow.


title: HOT RELOADING / FILE SYNCHRONIZATION
content:
A key feature of <i>devspace dev</i> mode. Instead of rebuilding and redeploying entire images for every code change, DevSpace intelligently synchronizes local file changes directly into the running container. This dramatically reduces the feedback loop, making development on Kubernetes feel similar to local development with a hot-reloading server.


title: HISTORY
content:
DevSpace was created by Loft.sh, a company focused on developer tooling for Kubernetes. It was first open-sourced around 2018-2019, aiming to solve common pain points developers faced when building applications for Kubernetes, such as slow iteration cycles, complex setup, and fragmented workflows. Its development has focused on simplifying the <code>devspace.yaml</code> configuration, improving hot-reloading capabilities, and integrating seamlessly with various Kubernetes environments. It has gained popularity for its ability to provide a "Docker Compose"-like experience for Kubernetes development.


title: TLDR
content:
<b>Initialize a new DevSpace project in the current directory</b>`devspace init`<br><b>Start development mode with port forwarding, file synchronization, and terminal access</b>`devspace dev`<br><b>Start development mode in a specific namespace</b>`devspace dev [[-n|--namespace]] [namespace]`<br><b>Deploy the project to Kubernetes</b>`devspace deploy`<br><b>Deploy the project with a specific profile</b>`devspace deploy [[-p|--profile]] [profile-name]`<br><b>Build all defined images</b>`devspace build`<br><b>Follow logs from a pod</b>`devspace logs [[-f|--follow]]`<br><b>Open the DevSpace UI in the browser</b>`devspace ui`


title: PARAMETERS
content:
<b><b>--filter</b>, <b>-f</b> <I>"filter"</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter output based on conditions provided. Supported filters include <I>is-automated</I> (true/false), <I>is-official</I> (true/false), <I>stars</I> (n, where n is a number of stars), and <I>name</I> (image name, supports regex).<br><br><b><b>--format</b> <I>"string"</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print search results using a Go template. This is useful for scripting or generating customized output formats.<br><br><b><b>--limit</b> <I>int</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of search results to return. The default limit is 25.<br><br><b><b>--no-trunc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents truncation of output. By default, descriptions and image names might be shortened for readability.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a usage statement and exits.<br><br>


title: DESCRIPTION
content:
The <b>docker search</b> command allows users to search the Docker Hub registry for available Docker images. It is a fundamental tool for discovering new images by providing a search term. The command queries the official Docker Hub by default, returning a list of images that match the specified criteria.<br><br>Results typically include the image name, a brief description, the number of stars (a popularity indicator), and flags indicating if the image is an official build or an automated build. Users can refine their search by filtering results based on various conditions, such as the number of stars, official status, or automation status. Additionally, the number of returned items can be limited. This command is crucial for exploring the vast ecosystem of pre-built container images and identifying suitable base images for applications.


title: CAVEATS
content:
The <b>docker search</b> command primarily searches the public Docker Hub registry. It does not search private registries or local images unless configured specifically through Docker's daemon configuration (which is generally outside the scope of this command's direct functionality). Network connectivity is required to perform searches, as it interacts with a remote service. Results are ordered by relevance, with star count being a strong indicator of an image's popularity and reliability.


title: OUTPUT COLUMNS
content:
When you run <b>docker search</b>, the output typically displays several columns of information for each matching image:<br><ul><li><I>NAME</I>: The full name of the image (e.g., <I>ubuntu</I>, <I>nginx</I>).</li><li><I>DESCRIPTION</I>: A brief text description provided by the image publisher.</li><li><I>STARS</I>: The number of users who have 'starred' the image, indicating its popularity and community approval.</li><li><I>OFFICIAL</I>: Indicates if the image is officially supported by Docker or the software vendor (e.g., <I>[OK]</I> for official images).</li><li><I>AUTOMATED</I>: Indicates if the image was built via an automated Docker Hub build process linked to a source code repository (e.g., <I>[OK]</I> for automated builds).</li></ul>


title: HISTORY
content:
The <b>docker search</b> command has been a fundamental component of the Docker CLI since its early versions, providing users with an intuitive way to discover and utilize the growing collection of container images available on Docker Hub. Its core functionality, which allows users to query the public registry, has remained consistent. Over time, incremental improvements, such as enhanced filtering and formatting options, have been added to improve usability and scriptability, reinforcing Docker's vision of an open and accessible container ecosystem.


title: TLDR
content:
<b>Search for Docker images by name or keyword</b>`docker search [keyword]`<br><b>Search for images and only show official ones</b>`docker search [[-f|--filter]] is-official=true [keyword]`<br><b>Search for images and only show automated builds</b>`docker search [[-f|--filter]] is-automated=true [keyword]`<br><b>Search for images with a minimum number of stars</b>`docker search [[-f|--filter]] stars=[number] [keyword]`<br><b>Limit the number of results</b>`docker search --limit [number] [keyword]`<br><b>Customize the output format</b>`docker search [[-f|--format]] "[.Name]: [.Description]" [keyword]`


title: SYNOPSIS
content:
<b>flask-unsign</b> [OPTIONS] COMMAND [ARGUMENTS]<br><br><i>Commands:</i><br>&nbsp;&nbsp;<b>unsign</b> &lt;cookie_value&gt; [OPTIONS]<br>&nbsp;&nbsp;<b>sign</b> &lt;payload&gt; [OPTIONS]<br>&nbsp;&nbsp;<b>crack</b> &lt;cookie_value&gt; [OPTIONS]


title: PARAMETERS
content:
<b>--secret <key></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the Flask application's secret key to use for signing or unsigning. This is required for signing and can be used for unsigning/cracking if known.<br><br><b>-c, --cookie <value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The Flask session cookie value to unsign or crack. This option is required when using the <b>unsign</b> or <b>crack</b> commands.<br><br><b>-p, --payload <value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The JSON payload (e.g., '{"user":"admin"}') to sign into a new cookie. This option is required when using the <b>sign</b> command.<br><br><b>-l, --legacy</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the legacy signing method (pre-<i>itsdangerous</i> v1.0). This might be necessary for older Flask applications.<br><br><b>--salt <value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom salt string used during the signing or unsigning process. Some Flask applications might use a custom salt.<br><br><b>--compress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply zlib compression before signing (for <b>sign</b> command) or decompress after unsigning (for <b>unsign</b> command). Flask can optionally compress session data.<br><br><b>-o, --output <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the command's output to the specified file instead of printing it to standard output (stdout).<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, providing more detailed information about the operation, which can be useful for debugging.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the help message and exit, showing available commands and options.<br><br><b>-w, --wordlist <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a wordlist file for brute-forcing the secret key. This option is specific to the <b>crack</b> command.<br><br><b>--no-guess</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not attempt to guess common secret keys before using the provided wordlist. This option is specific to the <b>crack</b> command.<br><br><b>--decode-base64</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decode the cookie value from Base64 before unsigning. This is useful for very old Flask versions or specific configurations where the cookie might be Base64 encoded prior to signing.<br><br>


title: DESCRIPTION
content:
<b>flask-unsign</b> is a powerful command-line utility designed for security researchers and penetration testers to analyze and manipulate Flask session cookies. Flask applications typically use the <i>itsdangerous</i> library to sign session cookies, ensuring their integrity and preventing tampering. <b>flask-unsign</b> leverages this mechanism by providing functionalities to:<br><b>Unsign cookies:</b> Decrypt the payload of a Flask session cookie, revealing its internal data. This is crucial for understanding the structure and content of sessions.<br><b>Sign cookies:</b> Forge new Flask session cookies with custom payloads, given the application's secret key. This allows testers to inject arbitrary data into sessions.<br><b>Crack secret keys:</b> Brute-force or use a wordlist to discover the secret key used by a Flask application to sign its cookies. This is often the primary goal, as possessing the secret key allows full control over session forging.<br>The tool supports different signing methods and features like compression and salt specification, adapting to various Flask/itsdangerous configurations. It is an invaluable asset in web application security audits and Capture The Flag (CTF) challenges involving Flask applications.


title: CAVEATS
content:
<b>flask-unsign</b> is a specialized tool for security auditing and educational purposes. It should only be used against systems with explicit permission. Its effectiveness relies on the <i>itsdangerous</i> library's signing mechanisms. If a Flask application employs custom, non-standard session management or encryption methods beyond <i>itsdangerous</i>, this tool may not be effective. Brute-forcing secret keys can be time-consuming and computationally intensive without a strong wordlist, and it's subject to rate-limiting or lockout mechanisms if performed against a live application.


title: USE CASES
content:
<b>flask-unsign</b> is primarily used in: <br><b>Penetration Testing:</b> Identifying and exploiting insecure session management in Flask applications.<br><b>CTF Challenges:</b> Solving web exploitation challenges where Flask session cookie manipulation is required.<br><b>Security Research:</b> Understanding how Flask sessions are signed and identifying potential weaknesses in the implementation.


title: INSTALLATION
content:
<b>flask-unsign</b> can typically be installed via Python's package manager <b>pip</b>: <br><b>pip install flask-unsign</b><br>It requires a Python environment to run.


title: HISTORY
content:
<b>flask-unsign</b> emerged as a necessity within the cybersecurity community, particularly among penetration testers and CTF players, to effectively analyze and exploit vulnerabilities in Flask web applications. Its development closely mirrors the evolution of the <i>itsdangerous</i> library, the primary session signing mechanism used by Flask. As <i>itsdangerous</i> introduced new signing methods (e.g., changes between v0.x and v1.x), <b>flask-unsign</b> has been updated to support these different schemes, ensuring its continued relevance and utility in a constantly evolving web security landscape. It provides a convenient, focused alternative to manually scripting decryption and signing operations.


title: SEE ALSO
content:
itsdangerous (Python library used by Flask for signing), jwt_tool (for JSON Web Token analysis, similar concept but for JWTs), hashcat (general-purpose password recovery utility, can be used for cracking other hashes)


title: TLDR
content:
<b>Decode a Flask session cookie</b>`flask-unsign [[-d|--decode]] [[-c|--cookie]] [cookie]`<br><b>Decode a session cookie fetched from a URL which returns a Set-Cookie header</b>`flask-unsign [[-d|--decode]] --server [URL]`<br><b>Brute-force a secret key using the default flask-unsign-wordlist (requires flask-unsign-wordlist)</b>`flask-unsign [[-u|--unsign]] [[-c|--cookie]] [cookie]`<br><b>Brute-force a secret key with a custom wordlist (use --no-literal-eval for unquoted entries)</b>`flask-unsign [[-u|--unsign]] [[-c|--cookie]] [cookie] [[-w|--wordlist]] [path/to/wordlist.txt]`<br><b>Sign a new session cookie with a secret key</b>`flask-unsign [[-s|--sign]] [[-c|--cookie]] "[{'logged_in': False]}" [[-S|--secret]] [secret]`<br><b>Sign a session cookie using legacy timestamp (useful for old versions)</b>`flask-unsign [[-s|--sign]] [[-c|--cookie]] "[{'logged_in': False]}" [[-S|--secret]] [secret] [[-l|--legacy]]`<br><b>Brute-force a session cookie with custom threads and no literal evaluation</b>`flask-unsign [[-u|--unsign]] [[-c|--cookie]] [cookie] [[-w|--wordlist]] [path/to/wordlist.txt] [[-t|--threads]] [threads] [[-nE|--no-literal-eval]]`


title: SYNOPSIS
content:
The concept of 'uv-init' typically involves:<br><b>uv venv</b> [<I>LOCATION</I>] [<I>OPTIONS</I>]<br><b>uv install</b> [<I>PACKAGES...</I>] [<I>OPTIONS</I>]<br><b>uv sync</b> [<I>OPTIONS</I>]


title: PARAMETERS
content:
<b><I>LOCATION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv venv`, the directory path where the new virtual environment should be created (e.g., `.venv`). If omitted, creates it in `.venv` in the current directory.<br><br><b>--python <I>PYTHON_EXECUTABLE_PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the Python interpreter to use for creating the virtual environment or for dependency resolution during installation. Example: `--python /usr/bin/python3.10`.<br><br><b>--python-version <I>VERSION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a Python version (e.g., `3.10`, `3.11`) to use for the environment or for resolving dependencies. `uv` will attempt to locate or download the specified version.<br><br><b>--seed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv venv`, ensures that essential tools like `pip` are installed within the newly created virtual environment. This is typically the default behavior.<br><br><b>--name <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv venv`, assigns a custom name to the virtual environment. This name might be used for easier reference, especially when managing multiple environments.<br><br><b>-r <I>FILE</I>, --requirement <I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv install` or `uv sync`, specifies a path to a requirements file (e.g., `requirements.txt`) containing a list of packages and their versions to install.<br><br><b>--dev</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv install` or `uv sync`, includes development dependencies (e.g., from `[project.optional-dependencies.dev]` in `pyproject.toml` if supported by the project layout).<br><br><b>--offline</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv install` or `uv sync`, prevents `uv` from accessing the network. It will only use packages available in its local cache, useful for offline development or reproducible builds.<br><br><b>--strict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv install` or `uv sync`, enforces strict dependency resolution. If `uv` detects any conflicting package versions that cannot be resolved, the command will fail rather than attempting a less strict installation.<br><br><b>[<I>PACKAGES...</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For `uv install`, a space-separated list of package names (and optional version specifiers) to install directly into the active environment (e.g., `uv install 'requests<3' Flask`).<br><br>


title: DESCRIPTION
content:
The command `uv-init` is not a standard, standalone Linux command. Instead, it refers to the process of initializing a Python project and its development environment using the `uv` tool. `uv` is a modern, fast, and robust Python package installer and resolver, designed as a direct replacement for `pip` and `virtualenv`, and a viable alternative to `pip-tools`, `Poetry`, or `Pipenv`.<br><br>Project initialization with `uv` primarily involves two key steps:<br><i>1. Environment Creation:</i> Using `uv venv` to create an isolated Python virtual environment where project dependencies will be installed.<br><i>2. Dependency Installation:</i> Utilizing `uv install` or `uv sync` to install required packages, typically specified in a `requirements.txt` file or `pyproject.toml`'s `[project.dependencies]` section.<br><br>This combined workflow effectively initializes a new Python project, setting up its dedicated environment and installing its initial set of dependencies, making `uv` a powerful tool for streamlining Python development workflows.


title: CAVEATS
content:
It is crucial to understand that `uv-init` is not a literal command you can type and execute. It is a conceptual term referring to the initialization actions performed using the `uv` tool, primarily `uv venv` and `uv install` or `uv sync`. `uv` itself is a relatively new and rapidly evolving tool; while stable, its exact command structure and features may see minor adjustments in future versions. Users should ensure they have `uv` installed (e.g., via `curl -LsSf https://astral.sh/uv/install.sh | sh`) before attempting these operations.


title: COMMON INITIALIZATION WORKFLOW
content:
A typical `uv` initialization workflow for a new Python project usually follows these steps:<br>1. Create a virtual environment: <b>uv venv .venv</b><br>2. Activate the environment: <b>source .venv/bin/activate</b> (on Linux/macOS) or <b>.venv\Scripts\activate</b> (on Windows)<br>3. Install dependencies from a file: <b>uv sync</b> (if `pyproject.toml` or `requirements.txt` exists) or <b>uv install -r requirements.txt</b><br>This sequence ensures an isolated, reproducible, and performant development setup.


title: WHY USE UV FOR INITIALIZATION?
content:
`uv` offers significant advantages for project initialization and ongoing dependency management:<br><i>1. Speed:</i> It is orders of magnitude faster than `pip` and `conda` for resolving and installing dependencies due to its Rust implementation and efficient algorithms.<br><i>2. Reproducibility:</i> `uv`'s robust resolver helps ensure that builds are more consistent across different environments.<br><i>3. Unified Tooling:</i> It aims to combine the functionalities of `pip`, `pip-tools`, and `virtualenv` into a single, cohesive command-line interface, simplifying the Python toolchain.


title: HISTORY
content:
`uv` emerged from `Astral.sh` (formerly `Rye`), an organization dedicated to building fast and efficient tools for Python development. Written in Rust, `uv` was designed from the ground up to address performance and reliability issues present in traditional Python package managers like `pip`. It aims to provide a unified, significantly faster, and more robust experience for dependency resolution and package installation, quickly gaining traction within the Python community since its public announcement in late 2023.


title: TLDR
content:
<b>Initialize a project in the current directory</b>`uv init`<br><b>Initialize a project with a certain name</b>`uv init [project_name]`<br><b>Create a project in a given directory</b>`uv init --directory [path/to/directory] [project_name]`<br><b>Create a project for a Python library</b>`uv init [[--lib|--library]] [project_name]`<br><b>Specify the build system</b>`uv init --build-backend [build_backend] [project_name]`<br><b>Only create a pyproject.toml</b>`uv init --bare [project_name]`<br><b>Set the project description</b>`uv init --description "[description]" [project_name]`


title: SYNOPSIS
content:
<i>claude</i> [OPTIONS] [PROMPT_OR_FILE]<br><br><b>Examples:</b><br><i>claude</i> <b>--prompt</b> "Explain quantum entanglement simply." <b>--model</b> sonnet<br><i>claude</i> <b>-f</b> my_long_prompt.txt <b>--stream</b> <b>-o</b> response.md


title: PARAMETERS
content:
<b>-p, --prompt &lt;text&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the text prompt to send to the Claude AI. Use quotes for multi-word prompts.<br><br><b>-f, --file &lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the prompt from the specified file path. Useful for longer or pre-prepared inputs.<br><br><b>-m, --model &lt;name&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select the Claude model to use (e.g., <i>opus</i>, <i>sonnet</i>, <i>haiku</i>). Defaults to a sensible choice if not specified.<br><br><b>-s, --stream</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stream the AI response as it is generated, displaying partial results in real-time.<br><br><b>-o, --output &lt;path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Save the AI's full response to the specified file path instead of printing to stdout.<br><br><b>-t, --temperature &lt;value&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Control the creativity/randomness of the AI response (0.0 for deterministic, 1.0 for highly creative). Default is typically 0.7.<br><br><b>-k, --api-key &lt;key&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide your Anthropic API key directly. This overrides the `ANTHROPIC_API_KEY` environment variable.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a concise help message and exit.<br><br>


title: DESCRIPTION
content:
The <i>claude</i> command-line interface (CLI) tool provides a seamless way to interact with Anthropic's Claude large language models directly from your terminal. It enables users to send text prompts, specify different Claude models (e.g., Opus, Sonnet, Haiku), and receive AI-generated responses. Designed for developers, researchers, and power users, <i>claude</i> facilitates rapid prototyping, automated scripting, and efficient AI-driven workflows without requiring a web browser or dedicated application. Users can tailor responses by adjusting parameters like temperature for creativity, stream output for real-time interaction, and save responses to files for further processing. The command integrates easily into shell scripts, offering a powerful bridge between your command line environment and cutting-edge AI capabilities.


title: CAVEATS
content:
The <i>claude</i> command requires an active internet connection to communicate with Anthropic's API. An Anthropic API key is necessary for authentication and usage, which may incur costs based on usage. Be mindful of rate limits imposed by the API. Sensitive information should ideally not be passed directly via command-line arguments if logging is enabled on your system; consider using environment variables or file inputs for API keys and confidential prompts.


title: ENVIRONMENT VARIABLES
content:
The <i>claude</i> command typically looks for the Anthropic API key in the `ANTHROPIC_API_KEY` environment variable. Setting this variable (`export ANTHROPIC_API_KEY="your_key_here"`) prevents the need to pass the key with every command invocation, enhancing security and convenience.


title: EXIT STATUS
content:
The command returns <b>0</b> on successful execution. Non-zero values indicate an error (e.g., <b>1</b> for general errors, <b>2</b> for invalid arguments, <b>3</b> for API-specific errors like network issues or invalid API keys). Specific error codes may vary based on the underlying API response and client implementation.


title: HISTORY
content:
The <i>claude</i> command, while a hypothetical representation of a direct CLI tool, embodies the growing trend in developer tools to integrate powerful AI models directly into command-line workflows. Its conceptual design is inspired by existing community-driven CLI projects and official SDKs that wrap complex AI APIs for ease of use in shell environments. This evolution reflects the increasing demand for accessible AI tools beyond web interfaces, enabling faster iteration and automation for tasks ranging from code generation to data analysis, making AI an integral part of the Unix philosophy.


title: TLDR
content:
<b>Execute with prompt</b>`claude prompt`<br><b>Update claude</b>`claude update`<br><b>Get the list of specified MCP servers</b>`claude mcp list`<br><b>Create commit with command</b>`claude commit`<br><b>Get the list of configurations</b>`claude config list`<br><b>Continue the most recent session</b>`claude [[-c|--continue]]`<br><b>Interactively select a session to continue</b>`claude [[-r|--resume]]`


title: SYNOPSIS
content:
pbmtopng [<i>-verbose</i>] [<i>-compression N</i>] [<i>-interlace</i>] [<i>-transparent</i>] [<i>-gamma N</i>] [<i>-text text</i>] [<i>-time</i>] [<i>-comment text</i>] [<i>-sRGB</i>] [<i>pbmfile</i>]<br><br>Alternatively, commonly used with pipes:<br><i>any_image_command</i> | pbmtopng [<i>options</i>] > <i>output.png</i>


title: PARAMETERS
content:
<b><i>-verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints diagnostic information about the conversion process to standard error.<br><br><b><i>-compression N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the PNG compression level, where <i>N</i> is an integer from 0 (no compression) to 9 (maximum compression). The default is typically 6.<br><br><b><i>-interlace</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Adam7 interlacing, which allows an image to be progressively displayed as it downloads.<br><br><b><i>-transparent</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Makes the 'white' pixels (foreground in PBM) transparent in the output PNG image. Only applicable to monochrome PBM input.<br><br><b><i>-gamma N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embeds a gamma correction value (<i>N</i>) into the PNG, influencing how the image's brightness is displayed.<br><br><b><i>-text text</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embeds a generic text string into the PNG. Can be used multiple times for different text chunks (e.g., title, author).<br><br><b><i>-time</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embeds the current time and date into the PNG file's tIME chunk.<br><br><b><i>-comment text</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embeds a comment string into the PNG file.<br><br><b><i>-sRGB</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embeds an sRGB (standard Red Green Blue) color space chunk into the PNG, promoting consistent color rendering.<br><br>


title: DESCRIPTION
content:
The <i>pbmtopng</i> command is a fundamental utility within the Netpbm image manipulation suite. It specializes in converting images from the Portable BitMap (PBM) format to the Portable Network Graphics (PNG) format. PBM is a very simple, monochrome (black and white) image format, and <i>pbmtopng</i> efficiently transforms this 1-bit per pixel data into the more widely supported and feature-rich PNG standard.<br><br>Typically, <i>pbmtopng</i> reads a PBM image from its standard input and writes the resulting PNG image to its standard output, making it ideal for use in command-line pipelines. This allows users to chain operations, for example, converting a different image format to PBM first (e.g., using <i>ppmtopbm</i> or <i>pgmtopbm</i>) and then piping the output directly to <i>pbmtopng</i>. The command provides options to control PNG-specific features like compression level, interlacing, transparency (for one of the monochrome colors), and embedding metadata.


title: CAVEATS
content:
<i>pbmtopng</i> strictly expects a PBM (Portable BitMap) image as input. If your image is in another Netpbm format (PGM for grayscale, PPM for color), you must first convert it to PBM using commands like <i>pgmtopbm</i> or <i>ppmtopbm</i> before piping it to <i>pbmtopng</i>. Due to PBM's monochrome nature, the <i>-transparent</i> option only applies to one of the two colors (usually the 'white' background).


title: STANDARD INPUT/OUTPUT USAGE
content:
<i>pbmtopng</i> is designed to operate seamlessly with standard input and output. This allows it to be easily integrated into shell scripts and command pipelines. For example, to convert a PPM image to PBM and then to PNG, you would use: <i>ppmtopbm image.ppm | pbmtopng > image.png</i>. When an input file is specified as an argument, it reads from that file instead of standard input.


title: HISTORY
content:
<i>pbmtopng</i> is part of the Netpbm project, a comprehensive set of graphics tools developed by Jef Poskanzer starting in the early 1980s. Netpbm emerged from the earlier 'pbmplus' package. The suite is known for its simple, pipe-friendly design, where each tool performs a single, well-defined image manipulation task. <i>pbmtopng</i> was developed as part of this evolution to integrate PNG support into the ecosystem, maintaining Netpbm's modular philosophy.


title: PARAMETERS
content:
<b><b>-c</b> <I>dir</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use an alternative directory for configuration files, user profiles, and chat logs instead of the default <b>~/.purple/</b>.<br><br><b><b>--config=</b><I>dir</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Long form of <b>-c</b>, specifies an alternative configuration directory for Pidgin.<br><br><b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose debug output to the standard error (console), useful for basic troubleshooting.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Long form of <b>-d</b>, enables verbose debug output.<br><br><b><b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable exhaustive debug output, including detailed information from loaded plugins and modules, for in-depth debugging.<br><br><b><b>--debug-all</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Long form of <b>-D</b>, enables exhaustive debug output.<br><br><b><b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent Pidgin from attempting to open via D-Bus, forcing a new instance of the application even if one is already running.<br><br><b><b>--no-remote</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Long form of <b>-n</b>, prevents remote D-Bus activation.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the Pidgin version information and then exit immediately.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Long form of <b>-v</b>, displays version information and exits.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message with available command-line options and then exit.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Long form of <b>-h</b>, displays a help message and exits.<br><br>


title: DESCRIPTION
content:
Pidgin is a free and open-source multi-protocol instant messaging client. It enables users to connect to various chat networks simultaneously, including AIM, ICQ, Jabber/XMPP (Google Talk), MSN Messenger, Yahoo!, Bonjour, and more. Primarily a graphical application, Pidgin provides a unified interface for managing conversations across different services. It is well-known for its extensibility through a robust plugin system, offering additional features like encryption, spell checking, and various UI enhancements. When launched from the command line, it offers options primarily for specifying alternative configuration directories, enabling detailed debug output, or controlling its interaction with D-Bus, making it useful for developers, system administrators, and advanced users to troubleshoot or manage multiple configurations.


title: CAVEATS
content:
Pidgin is primarily a graphical user interface (GUI) application. While it can be launched from the terminal, its command-line options are mainly for debugging, managing configurations, or controlling instance behavior rather than performing direct messaging operations. Running with extensive debug options (<b>-d</b>, <b>-D</b>) can generate a large volume of output, potentially impacting terminal performance or quickly filling logs.


title: CONFIGURATION FILES
content:
By default, Pidgin stores its user-specific configuration, chat logs, account information, and plugin data within the <b>~/.purple/</b> directory. This directory is critical for user data persistence and can be redirected to an alternative location using the <b>-c</b> or <b>--config</b> command-line options.<br>User-installed plugins are typically placed in the <b>~/.purple/plugins/</b> subdirectory.


title: ENVIRONMENT VARIABLES
content:
The <b>PIDGIN_DEBUG</b> environment variable can be set to control the level of debug output, offering an alternative to command-line options for persistent debugging across multiple sessions or script-based launches without modifying the command itself.


title: HISTORY
content:
Pidgin originated as <i>Gaim</i> (GTK+ AOL Instant Messenger) in 1999. Due to legal pressure from AOL regarding the 'AIM' trademark in its name, it was officially renamed to Pidgin in 2007. It quickly became a popular open-source instant messaging client on Linux and other Unix-like systems, offering a unified messaging experience before the widespread adoption of web-based or single-protocol mobile clients. Despite shifts in messaging paradigms, Pidgin continues to be maintained and used by a dedicated community.


title: SYNOPSIS
content:
<B>po4a</B> [<I>options</I>] <I>configuration_file</I><br><br><B>po4a</B> is primarily a wrapper script that orchestrates the execution of underlying <B>po4a</B> tools like <B>po4a-gettextize</B> and <B>po4a-updatepo</B> based on a provided configuration file. While the core tools can be invoked directly for specific tasks, the wrapper with a configuration file is the most common and recommended way to manage complex translation projects.


title: PARAMETERS
content:
<b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase verbosity of output messages.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug messages for detailed operation insights.<br><br><b>--srcdir <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the base directory for master (source) files.<br><br><b>--destdir <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the base directory for localized (translated) output files.<br><br><b>--po-dir <dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the directory where PO files are located or will be created.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force execution, even if files appear up-to-date.<br><br><b>-k, --keep</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent deletion of temporary files generated during processing.<br><br><b>--localized-charset <charset></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the character encoding for the localized output files.<br><br><b>--master-charset <charset></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the character encoding for the master (source) files.<br><br><b>--po-charset <charset></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the character encoding for the PO files.<br><br><b>--no-translator-comments</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not add comments from translators to the PO files.<br><br><b>--set-po-version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the PO file revision-date to the current date and time.<br><br><b>--porevision-id <id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the PO-Revision-ID field in the PO file header.<br><br><b>--msgid-bugs-address <email></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the Msgid-Bugs-Address field in the PO file header.<br><br><b>--copyright-holder <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the Copyright-Holder field in the PO file header.<br><br><b>--pot-creation-date <date></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the POT-Creation-Date field in the POT file header.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output version information and exit.<br><br>


title: DESCRIPTION
content:
<I>po4a</I> (PO for Anything) is a powerful and versatile suite of tools designed to streamline the localization of various text-based formats, including documentation, configuration files, and other structured text. It acts as a crucial bridge between common document formats such as Man pages, DocBook, LaTeX, Markdown, Pod, XML, and the widely-used Gettext internationalization system. The core workflow involves converting an original document into a Gettext Portable Object (PO) file, which contains all translatable strings. Translators then utilize standard Gettext tools like <I>poedit</I> or <I>msgfmt</I> to translate this PO file. Once the translation is complete, <I>po4a</I> can seamlessly merge the translated strings back into the original document format, generating a fully localized version. This innovative approach centralizes translation efforts, leverages mature and robust translation tools, and ensures consistency across diverse document types by standardizing the translation process through PO files. <I>po4a</I> is particularly valuable for open-source projects, software documentation, and any endeavor requiring efficient maintenance of multi-language content.


title: CAVEATS
content:
<B>po4a</B> requires a solid understanding of the Gettext internationalization framework for effective use. Its powerful flexibility means configuration can become complex, especially when dealing with numerous document formats or a large number of languages. While highly robust, its reliance on specific format parsers means that unusual or malformed syntax in source documents might occasionally lead to unexpected parsing issues. Furthermore, <B>po4a</B> is primarily a command-line utility designed for automated batch processing, not a graphical editor, requiring users to be comfortable with terminal-based workflows and external Gettext translation tools.


title: CONFIGURATION FILES
content:
<B>po4a</B> projects are typically managed using a <B>po4a.conf</B> file. This plain-text configuration defines the translation units, specifies the source (master) and destination (localized) paths, sets up format-specific options, and links PO files to document pairs. This centralized configuration enables complex multi-document, multi-language localization workflows to be consistently automated.


title: SUPPORTED FORMATS
content:
<B>po4a</B> boasts extensive support for a wide array of document and text formats, thanks to its modular design. Notable supported formats include <I>man</I>, <I>pod</I>, <I>sgml</I>, <I>xml</I>, <I>docbook</I>, <I>latex</I>, <I>markdown</I>, <I>texinfo</I>, <I>text</I>, <I>ini</I> files, <I>yml</I> files, and many more. Each format is handled by a dedicated parser module, ensuring accurate extraction and merging of translatable strings.


title: TYPICAL WORKFLOW
content:
The standard <B>po4a</B> workflow involves three conceptual steps, often automated by the main <B>po4a</B> wrapper script and configuration: <BR>1. <B>Extraction</B>: Using <B>po4a-gettextize</B> to extract translatable strings from master documents into initial PO (or POT) files.<BR>2. <B>Synchronization & Merging</B>: Using <B>po4a-updatepo</B> to keep PO files synchronized with updates in master documents and to merge new translations from translators.<BR>3. <B>Generation</B>: Using <B>po4a-translate</B> (or implicitly by <B>po4a-updatepo</B>) to generate localized versions of the documents from the translated PO files.


title: HISTORY
content:
<B>po4a</B> development was initiated by Nicolas François, primarily driven by the need to efficiently translate documentation within the Debian project. The first significant public releases appeared around 2002-2003. Since then, it has been under continuous development and maintenance, steadily expanding its support for various document formats and enhancing its parsing capabilities. Its design focuses on leveraging the mature and widely adopted Gettext system, making it a robust solution for large-scale documentation localization.


title: DESCRIPTION
content:
The command 'ppdi' is not a standard or widely recognized utility in common Linux distributions. There is no publicly available manual page or common package that provides a command named 'ppdi'. <br><br>It is highly probable that 'ppdi' refers to one of the following:<br>- A typo for another existing Linux command (e.g., related to printing, system diagnostics, or data manipulation).<br>- A custom script or alias specifically created by a user or administrator on a particular system, tailored for a unique purpose.<br>- A command that is part of a very niche, specialized, or proprietary software package not commonly found in general-purpose Linux installations.<br>- An acronym that is not directly a command, such as 'PostScript Printer Description (PPD) files' often used in Linux printing, but 'ppdi' itself does not denote a standard executable.<br><br>Without additional context about its origin or specific system, it is not possible to provide a definitive description, syntax, or list of parameters for a standard 'ppdi' command.


title: CAVEATS
content:
As 'ppdi' is not a standard Linux command, attempting to execute it on most Linux systems will result in a 'command not found' error. If 'ppdi' is executable on a specific system, its functionality, behavior, and any associated risks would be entirely dependent on its unique implementation and purpose.


title: IDENTIFYING CUSTOM COMMANDS
content:
If 'ppdi' functions on your specific system, you can attempt to identify its nature and source. Use the <i>type ppdi</i> command to determine if it is an alias, a shell function, or an executable file. If it's an executable, <i>which ppdi</i> can reveal its path. For executable files, package managers like <i>dpkg -S /path/to/ppdi</i> (on Debian/Ubuntu-based systems) or <i>rpm -qf /path/to/ppdi</i> (on Red Hat/CentOS-based systems) might indicate which package provided it. If it's a script, inspecting the script's content at the identified path would be necessary to understand its purpose.


title: SYNOPSIS
content:
<B>ppmtogif</B> [<I>options</I>] [<I>ppmfile</I>]<br>If <I>ppmfile</I> is omitted, <B>ppmtogif</B> reads from standard input.


title: PARAMETERS
content:
<b>-interlace</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Produces an interlaced GIF file</B>, which allows web browsers to display a blurry version of the image before it's fully downloaded.<br><br><b>-sort</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Sorts the colors in the GIF colormap</B>. Useful for certain applications or for making the colormap more predictable.<br><br><b>-transparent <color></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Specifies a color to be made transparent</B> in the output GIF. The color can be specified as a name (e.g., "red"), hex code (e.g., "#FF0000"), or RGB values.<br><br><b>-background <color></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Sets the background color</B> for transparent pixels, used if the image is displayed without an alpha channel.<br><br><b>-alpha <alphafile></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Reads alpha channel information from a separate PGM file</B> (<I>alphafile</I>) to determine transparency.<br><br><b>-comment <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Adds a comment string</B> to the GIF file's header.<br><br><b>-map <mapfile></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Uses the colormap from a specified PPM or PGM file</B> (<I>mapfile</I>) for color reduction.<br><br><b>-maxcolors <N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Limits the output GIF to at most N colors</B>. Default is 256. <I>ppmtogif</I> will reduce the color count if necessary.<br><br><b>-dither</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Enables dithering</B> (default if color reduction occurs) to simulate colors not in the palette.<br><br><b>-nodither</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Disables dithering</B>, forcing the closest available color for each pixel.<br><br><b>-colorfuzz <N></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Sets a fuzz factor</B> (0-100) for color matching, used for transparency or mapping. Higher values make similar colors match.<br><br><b>-floyd_steinberg</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Uses the Floyd-Steinberg dithering algorithm</B> (this is the default when dithering is enabled).<br><br><b>-closest_color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Chooses the closest color</B> from the palette without dithering (same as <I>-nodither</I>).<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<B>Prints detailed information</B> about the conversion process to standard error.<br><br>


title: DESCRIPTION
content:
<I>ppmtogif</I> is a powerful command-line utility from the Netpbm suite, designed to convert image files from the Portable Pixmap (PPM) format to the Graphics Interchange Format (GIF). It's highly versatile, capable of handling color reduction, dithering, and various GIF-specific features like interlacing and transparency. Often used as part of a larger image processing pipeline, <I>ppmtogif</I> excels at transforming full-color PPMs into the 256-color indexed GIF format, making it suitable for web graphics and other applications requiring compressed, indexed color images. It automatically applies dithering when reducing colors, which can be controlled or disabled via options. Its ability to specify a transparent color or an external alpha channel file enhances its utility for creating complex web animations or overlays.


title: CAVEATS
content:
<I>ppmtogif</I> is subject to the limitations of the GIF format itself, primarily its 256-color palette. While <I>ppmtogif</I> excels at reducing full-color images to this palette, the result may not always perfectly replicate the original, especially for images with gradients or many subtle color variations. For higher color depths or lossless compression, consider PNG. Historically, GIF's LZW compression patent caused issues, but this patent has long expired, making GIF usage free. The Netpbm philosophy often involves piping output from one command to another, so <I>ppmtogif</I> is frequently used in combination with other Netpbm tools.


title: STANDARD INPUT/OUTPUT USAGE
content:
<B>ppmtogif</B> typically reads a PPM file from standard input if no filename is specified, and writes the GIF output to standard output. This allows for powerful piping operations, e.g., <I>anytoppm | ppmtogif > output.gif</I>.


title: COLOR SPECIFICATION
content:
Colors for options like <I>-transparent</I> or <I>-background</I> can be specified using names (e.g., "red", "black"), hexadecimal RGB values (e.g., "#FF0000" for red), or decimal RGB components (e.g., "255,0,0").


title: HISTORY
content:
<I>ppmtogif</I> is an integral part of the Netpbm project, a long-standing open-source collection of graphics manipulation utilities. Netpbm itself originated from the pbmplus package in the late 1980s. The development of <I>ppmtogif</I> was crucial for enabling Unix users to convert images into the then-popular GIF format, particularly for early web development. Its history is intertwined with the evolution of image formats and the open-source movement's efforts to provide robust command-line tools for image processing. The tool had to navigate the complexities of GIF's LZW compression patent, which influenced its usage and alternatives for a period, though this is no longer an issue.


title: SYNOPSIS
content:
<b>pppoe-discovery</b> [<i>-I &lt;interface&gt;</i>] [<i>-s &lt;service&gt;</i>] [<i>-C &lt;AC_name&gt;</i>] [<i>-S &lt;service_name_list&gt;</i>] [<i>-t &lt;timeout&gt;</i>] [<i>-L &lt;num_padi&gt;</i>] [<i>-V</i>] [<i>-D</i>]


title: PARAMETERS
content:
<b>-I <interface></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Ethernet network interface to use for discovery, e.g., <i>eth0</i> or <i>enp0s3</i>. If omitted, it typically defaults to 'eth0'.<br><br><b>-s <service></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for Access Concentrators (ACs) offering a specific service. Only ACs providing this exact service name will respond.<br><br><b>-C <AC_name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Searches for a specific Access Concentrator by its advertised name. Only the AC with this name will respond.<br><br><b>-S <service_name_list></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a comma-separated list of service names to look for. ACs offering any of these services will respond.<br><br><b>-t <timeout></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the timeout in seconds to wait for PADO responses after sending PADI packets. The default is usually 10 seconds.<br><br><b>-L <num_padi></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of PADI (PPPoE Active Discovery Initiation) packets to send before giving up. The default is typically 1.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version number of the <b>pppoe-discovery</b> utility and exits.<br><br><b>-D</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debugging output, providing more verbose information about the discovery process.<br><br>


title: DESCRIPTION
content:
<b>pppoe-discovery</b> is a utility included in the <i>rp-pppoe</i> client package, designed to perform the discovery phase of the Point-to-Point Protocol over Ethernet (PPPoE). This initial phase is crucial for establishing a PPPoE connection.<br><br>The command works by sending PADI (PPPoE Active Discovery Initiation) broadcast packets on a specified Ethernet interface. PPPoE Access Concentrators (ACs) on the network that receive these PADI packets respond with PADO (PPPoE Active Discovery Offer) packets.<br><br>These PADO packets contain information about the AC, such as its name and the services it offers. <b>pppoe-discovery</b> collects and displays this information, allowing users to identify available ACs and choose a specific service or AC for their PPPoE connection. It's often used to verify network connectivity to an AC or to determine the correct AC name and service name required by PPPoE clients like <b>pppd</b>. It does not establish the PPPoE session itself, but rather provides the necessary details for subsequent connection attempts.


title: CAVEATS
content:
<b>pppoe-discovery</b> typically requires root privileges to send and receive raw Ethernet packets. It only performs the discovery phase and does not establish a PPPoE connection; for that, other tools like <b>pppd</b> are required. It operates at the Ethernet layer, meaning a working Ethernet interface and physical connection are necessary.


title: HISTORY
content:
<b>pppoe-discovery</b> is a component of the <i>rp-pppoe</i> (Roaring Penguin PPPoE) client package, which was primarily developed by Paul P. R. Rowland. This package has been a long-standing and widely used solution for PPPoE client functionality on Linux and other Unix-like systems, enabling internet connectivity through DSL and other PPPoE-based services since the early 2000s. The <b>pppoe-discovery</b> utility specifically was designed to simplify the initial setup and troubleshooting of PPPoE connections by automating the process of finding available Access Concentrators.


title: PARAMETERS
content:
<b>-I <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the network interface to sniff on. For example, <i>eth0</i> or <i>enp0s3</i>. If not specified, <b>pppoe-sniff</b> defaults to <i>eth0</i>.<br><br><b>-T <I>timeout</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum time in seconds to sniff for packets. The command will exit after this duration. Default is 30 seconds.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version number of <b>pppoe-sniff</b> and exits immediately.<br><br>


title: DESCRIPTION
content:
The <b>pppoe-sniff</b> command is a utility designed to detect PPPoE Access Concentrators (ACs) on a local network segment. It passively listens for PPPoE Active Discovery (PAD) packets, specifically PADO (PPPoE Active Discovery Offer) packets, which are sent by ACs in response to PADI (PPPoE Active Discovery Initiation) packets from clients. <br><br>This tool is invaluable for diagnosing PPPoE connection issues, identifying available ACs, and determining their MAC addresses, service names, and AC names. It operates by putting the specified network interface into promiscuous mode to capture all relevant PPPoE discovery traffic. By observing these packets, administrators can verify the presence and responsiveness of ACs, which is crucial for establishing a PPPoE connection.


title: CAVEATS
content:
<b>pppoe-sniff</b> requires root privileges to operate, as it needs to put the network interface into promiscuous mode and capture raw network packets. It only sniffs for discovery packets (PADI, PADO, PADR, PADS, PADT) and does not participate in the PPPoE session establishment itself. It relies on existing network traffic or active PPPoE client attempts (which would send PADI packets) to observe AC offers. If no clients are initiating discovery, it might not see any PADO packets unless ACs are configured to periodically send unsolicited offers (which is uncommon).


title: USAGE EXAMPLE
content:
To sniff on the <i>eth0</i> interface for 60 seconds:<br><i>sudo pppoe-sniff -I eth0 -T 60</i><br><br>To simply check for any ACs on the default interface for 30 seconds:<br><i>sudo pppoe-sniff</i>


title: OUTPUT FORMAT
content:
When <b>pppoe-sniff</b> detects an Access Concentrator, it typically outputs information like the MAC address of the AC, the AC name (if provided), and the service name (if provided) associated with the offer. This information is crucial for configuring a PPPoE client to connect to a specific AC or service.


title: HISTORY
content:
The <b>pppoe-sniff</b> utility is part of the <b>rp-pppoe</b> (Roaring Penguin PPPoE) client package, which has been a staple PPPoE client implementation for Linux and other Unix-like operating systems since the early 2000s. Developed to provide robust PPPoE connectivity, the <b>rp-pppoe</b> suite includes various tools for managing PPPoE sessions, and <b>pppoe-sniff</b> was included as a diagnostic aid for troubleshooting and discovering PPPoE access concentrators. Its design reflects the simplicity and directness typical of Unix command-line utilities.


title: DESCRIPTION
content:
`<b>pppoe-stop</b>` is a utility provided as part of the `<i>rp-pppoe</i>` (Roaring Penguin PPPoE) client suite for Linux. Its primary function is to gracefully terminate an active Point-to-Point Protocol over Ethernet (PPPoE) broadband internet connection previously established using commands like `<b>pppoe-start</b>`.<br><br>When invoked, `<b>pppoe-stop</b>` typically performs the following actions:<br><br><I>1. Identify Running Process:</I> It locates the Process ID (PID) of the `pppoe` daemon or the `pppoe-connect` script that is currently managing the active connection. This is often done by reading a PID file, commonly located at `<i>/var/run/pppoe-connect.pid</i>` or `<i>/var/run/pppoe.pid</i>`.<br><I>2. Send Termination Signal:</I> It sends a termination signal (usually `SIGTERM`) to the identified process, requesting it to shut down cleanly.<br><I>3. Force Kill (if necessary):</I> If the process does not respond to the `SIGTERM` within a reasonable timeout, `<b>pppoe-stop</b>` may send a more forceful `SIGKILL` signal to ensure the process is terminated.<br><I>4. Cleanup:</I> It ensures that the network interface associated with the PPPoE connection is properly brought down, and any temporary files or resources allocated by the connection are released.<br><br>This command is essential for users to manage their broadband connections, allowing them to disconnect when necessary, freeing up network resources and the public IP address. Due to its interaction with network interfaces and system processes, `<b>pppoe-stop</b>` usually requires root privileges to execute successfully.


title: CAVEATS
content:
<I>1. Root Privileges:</I> Requires root privileges or `<b>sudo</b>` to execute, as it interacts with system-level processes and network interfaces.<br><I>2. PID File Dependency:</I> Its success heavily depends on the presence and correctness of the PID file (e.g., `<i>/var/run/pppoe-connect.pid</i>`). If this file is missing, corrupt, or contains an incorrect PID, `<b>pppoe-stop</b>` may fail to identify and terminate the running connection.<br><I>3. Single Connection:</I> Typically designed to stop the <I>one</I> active PPPoE connection managed by `<b>pppoe-start</b>`. If multiple complex PPPoE configurations are running (which is uncommon with `rp-pppoe`), this command might only affect the primary one.<br><I>4. Wrapper Script:</I> `<b>pppoe-stop</b>` is often a high-level shell script that calls underlying system commands (`kill`, `rm`). Problems can arise if these underlying commands fail or if the environment is unexpected.


title: USAGE WITH SUDO
content:
Due to its system-level operations, `<b>pppoe-stop</b>` must almost always be run with `<b>sudo</b>` privileges: `<b>sudo pppoe-stop</b>`.


title: PID FILE LOCATION
content:
The command typically looks for the PID of the running `pppoe-connect` process in a file like `<i>/var/run/pppoe-connect.pid</i>`. Ensure this file is present and valid for the command to function correctly.


title: HISTORY
content:
The `<b>pppoe-stop</b>` command is an integral part of the <I>Roaring Penguin PPPoE client (rp-pppoe)</I> suite, which gained prominence in the early 2000s. It was developed to provide a straightforward command-line interface for managing PPPoE connections on Linux systems, a common method for broadband internet access (especially ADSL) at the time. Its development paralleled the widespread adoption of PPPoE, offering a robust and reliable way to initiate and terminate these connections from the command line, complementing the `<b>pppoe-start</b>` command.


title: PARAMETERS
content:
<b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform reverse conversion. This is used when converting <I>groff</I>'s internal character representation back to an external encoding for output.<br><br><b><b>-L</b> <I>encoding</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output encoding for the conversion. This determines the character set to which the input will be converted.<br><br><b><b>-I</b> <I>encoding</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the input encoding. This informs <I>preconv</I> about the character set of the source <I>file</I>(s) or standard input.<br><br><b><I>file</I>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input files to be processed. If no files are specified, <I>preconv</I> reads from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<I>preconv</I> is an internal utility of the <I>groff</I> typesetting system, primarily used to convert character encodings of input files. It processes input to a common internal representation that <I>groff</I>'s <I>troff</I> formatter and its preprocessors (like <I>eqn</I> for equations or <I>tbl</I> for tables) can understand. <br><br>It acts as a crucial pre-processor, typically invoked automatically by <I>groff</I> when needed, rather than being run directly by users from the command line. <I>preconv</I> handles various input encodings (e.g., UTF-8, Latin-1) and ensures that special characters, non-ASCII characters, and multi-byte characters are correctly interpreted. This guarantees consistent and accurate rendering of documents, especially those containing diverse character sets or international text.


title: CAVEATS
content:
<I>preconv</I> is primarily an internal component of the <I>groff</I> typesetting pipeline and is not typically intended for direct user invocation. Its behavior is largely orchestrated and controlled by the main <I>groff</I> command's options and environment settings. For general character encoding conversion, the <I>iconv</I>(1) utility is usually more appropriate.


title: INPUT/OUTPUT
content:
<I>preconv</I> reads input from the files specified on the command line, or from standard input (stdin) if no files are provided. The converted output is then written to standard output (stdout).


title: INTERNAL OPERATION
content:
While <I>preconv</I> can be run manually, its primary function is within the automated <I>groff</I> pipeline. <I>groff</I> automatically detects the need for character conversion based on input characteristics and system locale, and then intelligently inserts <I>preconv</I> into the processing chain before the main <I>troff</I> formatter or other preprocessors. This makes its operation largely transparent to the end user.


title: HISTORY
content:
<I>preconv</I> has been an integral part of the <I>groff</I> (GNU <I>roff</I>) typesetting system almost since its inception. <I>groff</I> was developed as a free replacement for the AT&T <I>roff</I> and <I>troff</I> text formatters. As <I>groff</I> evolved to support internationalization and diverse character sets, <I>preconv</I> became crucial for ensuring that documents written in various encodings (like UTF-8) could be correctly processed and formatted. Its role is fundamental in <I>groff</I>'s robust handling of diverse text inputs, making it a critical, albeit often hidden, component of the typesetting pipeline.


title: PARAMETERS
content:
<b><<i>afm_file</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Adobe Font Metrics (AFM) file whose contents are to be displayed. This file must exist and be readable.<br><br>


title: DESCRIPTION
content:
<b>printafm</b> is a utility program designed to read an Adobe Font Metrics (AFM) file and output its detailed contents to standard output in a human-readable format.<br><br>AFM files are plain text files that provide critical font metric information for PostScript Type 1 fonts, including character dimensions, kerning pairs, and global font properties. This tool is invaluable for developers, font designers, and system administrators who need to inspect, verify, or troubleshoot font metric data. It allows users to quickly examine properties such as character bounding boxes, font-wide attributes (e.g., <i>FontName</i>, <i>Weight</i>), and kerning adjustments, making it easier to understand how a font is intended to be laid out and rendered by applications.


title: CAVEATS
content:
<b>printafm</b> has the following considerations:<br> - Input must be a valid AFM file; malformed files may lead to errors or unexpected output.<br> - The output is textual and can be extensive for fonts with many characters or complex kerning tables.<br> - This command is solely for viewing AFM file contents; it does not modify or convert fonts.


title: AFM FILE FORMAT
content:
Adobe Font Metrics (AFM) files are ASCII text files used to describe the characteristics of Type 1 PostScript fonts. They contain information essential for proper text layout, such as character widths, height, baseline positions, kerning pairs, and bounding boxes for each glyph. Applications like DTP software and PostScript interpreters use AFM files to accurately place characters and lines of text.


title: OUTPUT DETAILS
content:
The output of <b>printafm</b> includes various sections reflecting the structure of an AFM file. This typically comprises:<br><b>Global Font Information:</b> FontName, FullName, Weight, ItalicAngle, BoundingBox for the entire font.<br><b>Character Metrics:</b> Detailed information for each character, including its character code (e.g., <i>C 32</i> for space), character name, width (<i>WX</i>), and bounding box (<i>B</i>).<br><b>Kerning Data:</b> Listings of kerning pairs (<i>KPX</i> entries), specifying adjustments between specific character combinations (e.g., for 'VA' or 'Wo').<br>The textual output can be easily piped to other commands or redirected to a file for further processing or archival.


title: HISTORY
content:
<b>printafm</b> is typically distributed as part of the Ghostscript suite of utilities, a powerful interpreter for PostScript and PDF languages. Ghostscript's development began in the late 1980s, and accompanying tools like <b>printafm</b> likely emerged to support the growing need for inspecting and understanding font metrics in the PostScript ecosystem. Its fundamental purpose, to provide a plain-text view of AFM data, has remained consistent, serving as a reliable tool for font analysis within the broader PostScript and PDF processing workflows.


title: SYNOPSIS
content:
<b>prlimit</b> [<i>options</i>] <i><pid></i><br><b>prlimit</b> [<i>options</i>] <i><pid></i> [<i><resource></i> [<i><soft_value></i>[:<i><hard_value></i>]]]<br><b>prlimit</b> [<i>options</i>] <b>--pid</b> <i><pid></i> <b>--resource</b> <i><resource></i> [<b>--soft</b> <i><soft_value></i>] [<b>--hard</b> <i><hard_value></i>]<br><b>prlimit</b> [<i>options</i>] <i><command></i> [<i><arguments></i>...]


title: PARAMETERS
content:
<b>-p, --pid <i><pid></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the process ID to query or modify. Required when operating on a running process.<br><br><b>-r, --resource <i><resource></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the resource limit to query or set. Common resources include <b>nofile</b> (open files), <b>nproc</b> (number of processes), <b>cpu</b> (CPU time), <b>as</b> (address space), <b>core</b> (core file size).<br><br><b>-s, --soft <i><value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the soft limit for the specified resource. This is the current effective limit.<br><br><b>-h, --hard <i><value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the hard limit for the specified resource. This is the ceiling that the soft limit cannot exceed.<br><br><b>-o, --output <i><file></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects output to a specified file instead of standard output.<br><br><b>-R, --raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays output in raw format, without human-readable units.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides more detailed output regarding the operation.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br>


title: DESCRIPTION
content:
<b>prlimit</b> is a command-line utility used to query and set the resource limits of a running process or to apply limits to a command before its execution.<br><br>It provides a more versatile and direct way to manipulate resource limits compared to the shell built-in <b>ulimit</b>, as it can operate on a specific process ID (PID). Resource limits control the maximum amount of system resources a process can consume, such as CPU time, memory, open file descriptors, and number of processes.<br><br>These limits consist of a soft limit (current effective limit) and a hard limit (a ceiling that the soft limit cannot exceed). <b>prlimit</b> is invaluable for system administrators and developers to fine-tune system stability, prevent resource exhaustion by runaway processes, and manage system resources efficiently for specific applications. It is part of the <i>util-linux</i> package.


title: CAVEATS
content:
Setting resource limits for a process requires appropriate permissions, typically root privileges, especially for increasing hard limits or modifying limits for processes owned by other users.<br><br>Hard limits can only be lowered by unprivileged users, not increased. Only the root user (or a process with CAP_SYS_RESOURCE capability) can increase hard limits.<br><br>Limits applied to a command using <b>prlimit</b> <i><command></i> will only affect that specific command and its immediate children, not the shell from which it was launched.


title: RESOURCE NAMES AND UNITS
content:
The <i><resource></i> argument can be one of the following, usually represented in bytes, seconds, or number of items:<br><b>AS</b> (address space): total address space in bytes.<br><b>CORE</b> (core file size): maximum size of a core file in bytes.<br><b>CPU</b> (CPU time): maximum CPU time in seconds.<br><b>DATA</b> (data segment size): maximum size of the data segment in bytes.<br><b>FSIZE</b> (file size): maximum size of files created in bytes.<br><b>LOCKS</b> (locked locks): maximum number of file locks.<br><b>MEMLOCK</b> (locked memory): maximum memory that can be locked in RAM in bytes.<br><b>MSGQUEUE</b> (message queue size): maximum memory used by POSIX message queues in bytes.<br><b>NICE</b> (nice value): maximum nice value (lower is higher priority).<br><b>NOFILE</b> (open files): maximum number of open file descriptors.<br><b>NPROC</b> (number of processes): maximum number of processes for the user.<br><b>RSS</b> (resident set size): maximum resident set size in bytes.<br><b>RTPRIO</b> (realtime priority): maximum realtime priority.<br><b>SIGPENDING</b> (pending signals): maximum number of pending signals.<br><b>STACK</b> (stack size): maximum stack size in bytes.<br><br>The special value <i>unlimited</i> (or <i>-1</i>) can be used for any resource to indicate no limit.


title: DISPLAYING AND SETTING LIMITS
content:
When <b>prlimit</b> is run with only a PID (e.g., <i>prlimit 12345</i>), it displays all current soft and hard limits for that process in a human-readable format.<br><br>To set limits, specify the resource and optionally the soft and hard values. If only one value is given, it sets both soft and hard limits to that value. For example:<br><i>prlimit --pid 12345 --nofile 1024</i>  sets both soft and hard <b>nofile</b> limits to 1024.<br><i>prlimit --pid 12345 --nofile 512:1024</i> sets soft to 512 and hard to 1024 for <b>nofile</b>.


title: HISTORY
content:
<b>prlimit</b> is part of the <i>util-linux</i> project, a collection of essential system utilities for Linux. It was introduced to provide a more direct and flexible command-line interface to the <i>setrlimit(2)</i> and <i>getrlimit(2)</i> system calls, addressing some limitations and inconveniences of the older <b>ulimit</b> shell built-in. Its development aimed at offering better control over process resource limits, particularly for specific PIDs and for launching commands with predefined limits, contributing to better system resource management and stability.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>-c</b> <I>path</I>, <b>--config</b>=<I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the Prosody configuration file. Defaults to <i>/etc/prosody/prosody.cfg.lua</i> or similar.<br><br><b><b>-D</b> <I>path</I>, <b>--datadir</b>=<I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the Prosody data directory, where user data and other persistent information is stored.<br><br><b><b>-p</b> <I>path</I>, <b>--pidfile</b>=<I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to the PID file used by the Prosody daemon.<br><br><b><b>-H</b> <I>hostname</I>, <b>--host</b>=<I>hostname</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the virtual host for commands that operate on a specific domain (e.g., user management commands).<br><br><b><b>-u</b> <I>username</I>, <b>--user</b>=<I>username</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username for commands that operate on a specific user account.<br><br><b><b>-P</b> <I>password</I>, <b>--password</b>=<I>password</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the password for user management commands. Use with caution as it exposes the password in command history.<br><br><b><b>-X</b>, <b>--no-modules</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents Prosody from loading any modules when starting (primarily used for debugging).<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the Prosody version information and exits.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increases the verbosity of the output, showing more details about operations.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decreases the verbosity of the output, suppressing non-essential messages.<br><br><b><b>--daemon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the 'start' command to run Prosody in daemon mode (background).<br><br>


title: DESCRIPTION
content:
<i><b>prosodyctl</b></i> is the primary command-line utility used to control and manage the <I>Prosody XMPP server</I>. It provides a unified interface for administrators to perform a wide range of tasks, including starting, stopping, and restarting the server, managing user accounts (e.g., adding, deleting, changing passwords), inspecting server status and logs, generating and managing SSL/TLS certificates, and dynamically enabling or disabling modules. The command simplifies common administrative operations by interacting with the running Prosody daemon via a control socket, allowing many changes to take effect without requiring a server restart. It's an essential tool for day-to-day administration of a Prosody XMPP instance.


title: CAVEATS
content:
Many <i><b>prosodyctl</b></i> commands require appropriate permissions, often root or the user under which Prosody runs, to interact with the daemon or modify system files (e.g., starting/stopping the server, generating certificates).<br>For most commands to function, the Prosody server daemon must be running and its control socket accessible. If the server is stopped or the socket permissions are incorrect, commands interacting with the daemon will fail.


title: COMMON COMMANDS
content:
<i><b>prosodyctl</b></i> supports a variety of commands for different administrative tasks:<br><b>start</b>, <b>stop</b>, <b>restart</b>, <b>status</b>, <b>debug</b>, <b>reload</b> (for config changes), <b>adduser</b>, <b>deluser</b>, <b>passwd</b>, <b>register</b>, <b>unregister</b>, <b>cert</b> (generate/request/verify certificates), <b>modules</b> (enable/disable/list), <b>diagnose</b>, <b>shell</b> (for interactive Lua console), and <b>help</b>.


title: CONTROL SOCKET
content:
The primary mechanism for <i><b>prosodyctl</b></i> to communicate with a running Prosody instance is via a Unix domain socket, typically located at <i>/var/run/prosody/prosody.sock</i> or a similar path. This enables secure and efficient inter-process communication for administrative tasks without relying on network ports.


title: HISTORY
content:
<i><b>prosodyctl</b></i> was developed as an integral part of the <I>Prosody XMPP server</I> project, which was initiated in 2008 by Matthew Wild. Its design philosophy aligns with Prosody's core tenets of being lightweight, modular, and easy to configure. The utility has evolved alongside the server, incorporating new commands and options to reflect Prosody's expanding feature set and administrative needs. It leverages Prosody's robust internal control socket mechanism, which was a key design choice to enable dynamic server management without frequent restarts.


title: SYNOPSIS
content:
<b>protontricks</b> <i><appid|prefix_path></i> [<i>winetrick_verb</i>] [<i>winetricks_options...</i>]<br><b>protontricks</b> <i><option></i>


title: PARAMETERS
content:
<b><i><appid></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The Steam Application ID of the game whose Proton prefix should be targeted (e.g., <i>221680</i> for Fallout: New Vegas). This is the most common way to identify a prefix.<br><br><b><i><prefix_path></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An absolute path to a custom Proton prefix. Use this if the game is not managed by Steam directly or if the AppID detection fails.<br><br><b>[<i>winetrick_verb</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional <I>Winetricks</I> verb to apply immediately (e.g., <i>corefonts</i>, <i>vcrun2019</i>, <i>d3dcompiler_43</i>). If omitted, the <I>Winetricks</I> GUI will be launched for the specified prefix.<br><br><b>[<i>winetricks_options...</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Any additional options that should be passed directly to the underlying <I>Winetricks</I> command (e.g., <i>--unattended</i>, <i>--force</i>, <i>--no-isolate</i>). Refer to the <I>Winetricks</I> manual for a full list of available options.<br><br><b><b>--no-steam</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <I>protontricks</I> from attempting to launch Steam during the operation. Useful in headless environments or when you don't want Steam to interfere.<br><br><b><b>--gui</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the <I>Winetricks</I> graphical user interface to open for the selected prefix, even if a <I>winetrick_verb</I> was provided. This allows interactive selection of components.<br><br><b><b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the installation of a <I>winetrick_verb</I> even if <I>Winetricks</I> thinks it's already installed. This is passed directly to <I>Winetricks</I>.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, providing more verbose information about the execution process, which can be helpful for troubleshooting.<br><br><b><b>--skip-library-override</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <I>protontricks</I> from automatically setting DLL overrides after installing certain components. Use with caution.<br><br><b><b>--list-appids</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all Steam Application IDs for which <I>Proton</I> prefixes are detected on your system, along with their associated names.<br><br><b><b>--list-prefixes</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all detected <I>Proton</I> prefixes, including those not directly linked to a Steam AppID but found in common <I>Proton</I> locations.<br><br><b><b>--list-verbs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available <I>Winetricks</I> verbs that can be applied. This output comes directly from the underlying <I>Winetricks</I> utility.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with usage information and available options.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version information for <I>protontricks</I>.<br><br>


title: DESCRIPTION
content:
<i>protontricks</i> is a powerful BASH script designed to simplify the process of applying <I>Winetricks</I> commands to <I>Proton</I> prefixes. <BR><BR>When running Windows games via Steam Play (Proton) on Linux, certain applications or game components might require specific DLLs, runtimes, or other tweaks to function correctly. <I>Winetricks</I> is the standard utility for managing these dependencies within a Wine prefix. However, directly applying <I>Winetricks</I> to <I>Proton</I> prefixes can be complex due to <I>Proton</I>'s unique Wine build and prefix structure.<BR><BR><I>protontricks</I> acts as a smart wrapper, automatically locating the correct <I>Proton</I> prefix for a given Steam AppID or custom path, setting up the necessary environment variables, and then executing the specified <I>Winetricks</I> command. This makes it an indispensable tool for Linux gamers looking to resolve compatibility issues, install required dependencies like <I>DirectX</I> components, <I>Visual C++</I> runtimes, or specific fonts, and generally improve the stability and performance of their games running through <I>Proton</I>.


title: CAVEATS
content:
Using <i>protontricks</i> can sometimes have unintended side effects on a <I>Proton</I> prefix. It is always recommended to backup game saves and, if possible, the entire <I>Proton</I> prefix before applying complex <I>Winetricks</I> verbs. <BR><BR><i>protontricks</i> requires <I>Winetricks</I> to be installed on your system. It also relies on the specific <I>Wine</I> builds provided by <I>Proton</I>; thus, not all <I>Winetricks</I> verbs may function as expected or might conflict with <I>Proton</I>'s optimizations. For automatic AppID detection, Steam must be running.


title: USAGE EXAMPLES
content:
Here are some common ways to use <i>protontricks</i>:<BR><BR><b>Install corefonts for AppID 221680 (e.g., Fallout: New Vegas)</b>:<BR><i>protontricks 221680 corefonts</i><BR><BR><b>Install vcrun2019 for AppID 730 (e.g., CS:GO)</b>:<BR><i>protontricks 730 vcrun2019</i><BR><BR><b>Open the Winetricks GUI for AppID 221680</b>:<BR><i>protontricks 221680 --gui</i><BR><BR><b>List all detected Steam AppIDs and their names</b>:<BR><i>protontricks --list-appids</i><BR><BR><b>List all available Winetricks verbs</b>:<BR><i>protontricks --list-verbs</i>


title: APPID AND PREFIX DETECTION
content:
<I>protontricks</I> automatically attempts to locate the correct <I>Proton</I> prefix for a given Steam AppID. It typically searches in common Steam Library locations (e.g., <i>~/.steam/steam/steamapps/compatdata/</i> and other library folders). If a game's prefix isn't automatically detected, or if you are working with a custom prefix, you can provide the full path to the prefix directory as an argument instead of the AppID.


title: HISTORY
content:
<I>protontricks</I> emerged as a community-driven solution to a common challenge faced by Linux gamers: effectively using <I>Winetricks</I> with Valve's <I>Proton</I> compatibility layer. While <I>Proton</I> aims to provide out-of-the-box compatibility, many Windows games still require specific dependencies (like older <I>DirectX</I> runtimes or <I>Visual C++</I> redistributables) that <I>Winetricks</I> traditionally handles.<BR><BR>Before <I>protontricks</I>, users often had to manually locate <I>Proton</I> prefixes, set environment variables, and then invoke <I>Winetricks</I>, a cumbersome process. <I>protontricks</I> automated this, making it a staple utility for improving game compatibility and performance on <I>Proton</I>. Its development has been closely tied to the evolution of <I>Proton</I> and Steam Play, adapting to changes in prefix structure and <I>Proton</I> versions.


title: SYNOPSIS
content:
<b>ps2pdfwr</b> [<i>options</i>] <<i>input.ps</i>> [<i>output.pdf</i>]<br><br><i>Note: Most options are passed directly to the underlying <b>gs</b> command.</i>


title: PARAMETERS
content:
<b><i>input.ps</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Required)</i> The path to the PostScript file to be converted.<br><br><b><i>output.pdf</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Optional)</i> The desired name for the output PDF file. If not specified, it defaults to the input filename with a ".pdf" extension.<br><br><b>-dCompatibilityLevel=<<i>version</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the PDF compatibility level (e.g., 1.4, 1.5).<br><br><b>-dPDFSETTINGS=/screen</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>(Implicit Default)</i> This setting is internally applied by <b>ps2pdfwr</b> to optimize for screen viewing, resulting in smaller files. Users can override this by passing other <b>-dPDFSETTINGS</b> values directly to <b>ps2pdfwr</b>, which will then be passed to <b>gs</b>. Other common values include <i>/ebook</i>, <i>/printer</i>, <i>/prepress</i>, <i>/default</i>.<br><br><b>-dDownsampleColorImages=<<i>bool</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables downsampling of color images (e.g., <b>true</b> or <b>false</b>).<br><br><b>-dColorImageResolution=<<i>dpi</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target resolution for downsampled color images (e.g., 72, 150).<br><br><b>-sPAPERSIZE=<<i>size</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the paper size for the output PDF (e.g., <b>a4</b>, <b>letter</b>). This might affect layout if the PostScript is not resolution-independent.<br><br><b>-dNOPAUSE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables pausing after each page, useful for scripting.<br><br><b>-dBATCH</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Processes the input file and exits, preventing interactive prompts.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses startup messages and reduces output verbosity.<br><br>


title: DESCRIPTION
content:
<i>ps2pdfwr</i> is a specialized shell script that utilizes the powerful Ghostscript (<b>gs</b>) interpreter to convert PostScript (PS) files into PDF documents. The "wr" in its name stands for "writer" or "web," indicating that its default settings are optimized for producing smaller file sizes, suitable for screen viewing, web distribution, or email attachments. This is typically achieved by applying aggressive compression, downsampling images, and subsetting fonts.<br><br>While it offers a convenient way to generate compact PDFs, users should be aware that the resulting document might have a lower visual quality compared to PDFs generated with higher-quality settings, such as those produced by <b>ps2pdf</b> without specific "screen" settings.


title: CAVEATS
content:
<b>Quality vs. Size:</b> <i>ps2pdfwr</i> prioritizes small file size, which often means lower image resolution and potential compromises in visual fidelity compared to print-optimized settings.<br><b>PostScript Features:</b> Not all complex PostScript features or transparency effects may be perfectly translated to PDF, especially with aggressive compression settings.<br><b>Dependencies:</b> Requires Ghostscript (<b>gs</b>) to be installed and accessible in the system's PATH.


title: DEFAULT INTERNAL SETTINGS
content:
<b>ps2pdfwr</b> internally configures Ghostscript with settings equivalent to <b>-dPDFSETTINGS=/screen</b>. This includes aggressive image downsampling (e.g., typically to 72 dpi for color/grayscale images), embedding only necessary font subsets, and applying high compression. These defaults are designed to ensure the output PDF is as small as possible while remaining readable on a screen.


title: USE CASES
content:
This command is ideal for converting large PostScript documents into compact PDFs for email attachments, web publishing, online document previews, or any scenario where bandwidth or storage is a concern, and absolute print fidelity is not the primary requirement.


title: HISTORY
content:
The <b>ps2pdf</b> family of scripts, including <b>ps2pdfwr</b>, <b>ps2pdf12</b>, <b>ps2pdf13</b>, and <b>ps2pdf14</b>, are long-standing components of the Ghostscript distribution. They were developed to simplify common PostScript-to-PDF conversion tasks by wrapping the complex <b>gs</b> command with predefined settings. <b>ps2pdfwr</b> specifically emerged to address the need for web-friendly, smaller PDF files, making it a convenient tool for document sharing where file size is critical.


title: PARAMETERS
content:
<b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Match all files that contain the pattern, not just the first occurrence if multiple files share the same name within the archive.<br><br><b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the block number where the match was found (relative to the start of the archive).<br><br><b><b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instead of printing matching lines, print a count of matching lines for each file.<br><br><b><b>-E</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret <I>pattern</I> as an Extended Regular Expression (ERE). This is often the default behavior for <I>grep</I>.<br><br><b><b>-F</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret <I>pattern</I> as a fixed string, not a regular expression.<br><br><b><b>-f</b> <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read patterns from the file <I>name</I>, one pattern per line.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief usage message and exit.<br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignore case distinctions in both the <I>pattern</I> and the input data.<br><br><b><b>-j</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decompress the archive using <I>bzip2</I> before searching. (Equivalent to <I>--bzip2</I>).<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List only the names of files within the archive that contain at least one match. Do not print the matching lines.<br><br><b><b>-L</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;List only the names of files within the archive that do <I>not</I> contain any matches.<br><br><b><b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prefix each output line with its 1-based line number within the file.<br><br><b><b>-P</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Interpret <I>pattern</I> as a Perl Compatible Regular Expression (PCRE).<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode: suppress all output. Exit status indicates whether matches were found (0 for match, non-zero for no match or error).<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress error messages about non-existent or unreadable files.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Invert the match; select non-matching lines instead of matching ones.<br><br><b><b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select only those lines containing matches that form whole words.<br><br><b><b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Select only those lines where the entire line matches the pattern exactly.<br><br><b><b>-y</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decompress the archive using <I>xz</I> (or <I>lzma</I>) before searching. (Equivalent to <I>--xz</I>).<br><br><b><b>-z</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decompress the archive using <I>gzip</I> before searching. (Equivalent to <I>--gzip</I>).<br><br>


title: DESCRIPTION
content:
<I>ptargrep</I> is a specialized command-line utility designed to search for text patterns within files stored inside <I>tar</I> archives. Its primary advantage is that it performs the search without requiring the user to extract the entire archive first, saving significant time and disk space, especially for large archives or when only specific files are of interest. It efficiently streams the content from the archive and applies a <I>grep</I>-like search. <br><br>While not universally present on all Linux distributions by default (it's often part of the <I>libarchive</I> project, which provides <I>bsdtar</I>), it offers a powerful way to inspect archive contents. It supports various compression formats like <I>gzip</I>, <I>bzip2</I>, and <I>xz</I> transparently, and includes many familiar options from the standard <I>grep</I> command.


title: CAVEATS
content:
The availability of <I>ptargrep</I> depends on the system's <I>tar</I> implementation. It's typically included with <I>bsdtar</I> (from the <I>libarchive</I> project) but may not be present by default on systems primarily using GNU <I>tar</I>. For very large archives or complex patterns, performance can still be a consideration. <I>ptargrep</I> is a read-only utility; it cannot modify the contents of the archive.


title: ARCHIVE SPECIFICATION
content:
The <I>archive</I> argument specifies the <I>tar</I> archive file to be searched. This can be a local file path or, in some cases, a device file.


title: FILE FILTERING
content:
The optional <I>files...</I> arguments allow users to specify specific files or directories within the archive to narrow down the search. If no files are specified, <I>ptargrep</I> searches all files within the archive that are not directories.


title: REGULAR EXPRESSION SUPPORT
content:
<I>ptargrep</I> supports various types of regular expressions, including basic regular expressions (BREs - default if not specified), extended regular expressions (EREs) with <B>-E</B>, and Perl-compatible regular expressions (PCREs) with <B>-P</B>. This provides flexibility for complex search patterns.


title: HISTORY
content:
<I>ptargrep</I> is a utility that originated as part of the <I>libarchive</I> project, an open-source library that provides a uniform API for reading and writing various archive formats. It was developed to offer a convenient and efficient way to search within <I>tar</I> archives, leveraging <I>libarchive</I>'s streaming capabilities. Its design reflects the common need to quickly inspect archive contents without a full extraction, mirroring the functionality of <I>grep</I> for regular files but extended to compressed archive formats.


title: SEE ALSO
content:
<I>grep</I>(1), <I>tar</I>(1), <I>bsdtar</I>(1), <I>zgrep</I>(1), <I>bzgrep</I>(1), <I>xzgrep</I>(1)


title: SYNOPSIS
content:
<b><code>ptpython3</code></b> [<i>OPTIONS</i>] [<i>FILE</i>] [<i>ARGUMENTS</i>]<br><br>Invoking <I>ptpython3</I> without arguments typically launches the interactive REPL. An optional <I>FILE</I> can be provided to execute a Python script, after which the REPL can optionally remain interactive. Any subsequent <I>ARGUMENTS</I> are passed to the script.


title: PARAMETERS
content:
<b>FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional: Path to a Python script to execute. If combined with --interactive, the REPL starts after script execution.<br><br><b>ARGUMENTS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional: Additional arguments passed to the script specified by FILE.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message and exits.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the ptpython3 version information and exits.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug mode, which can provide more verbose output for troubleshooting.<br><br><b>--config <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative path to a configuration file (default is ~/.ptpython/config.py).<br><br><b>--vi</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the key bindings to Vi mode by default upon startup.<br><br><b>--emacs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the key bindings to Emacs mode by default upon startup.<br><br><b>--disable-history</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the persistent command history for the current session.<br><br><b>--paste</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables paste mode, which is useful for pasting multiline code without unexpected indentation issues.<br><br><b>--interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the REPL to always start in interactive mode, even when a FILE is provided.<br><br><b>--exec-lines <text></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the given Python code lines before starting the REPL. Useful for setting up the environment.<br><br>


title: DESCRIPTION
content:
<I>ptpython3</I> is an advanced interactive Python shell built upon the powerful <I>prompt_toolkit</I> library. It serves as a superior alternative to the default Python interpreter, offering a significantly enhanced development experience. Key features include <B>real-time syntax highlighting</B> powered by Pygments, <B>smart autocompletion</B> that understands context, <B>multiline editing</B> for complex code blocks, and a persistent <B>command history</B>. It supports both Vi and Emacs key bindings, allowing users to choose their preferred editing style. While it provides many of the essential features found in more heavyweight REPLs like IPython, <I>ptpython3</I> aims to be lightweight and highly customizable, making it an excellent choice for developers who spend considerable time interacting with Python.


title: CAVEATS
content:
<li><I>Installation Requirement</I>: <br> <I>ptpython3</I> is not typically pre-installed on most Linux distributions. It usually requires manual installation via <I>pip</I>, the Python package installer.</li><br><li><I>Configuration</I>: <br> Customization relies on a Python configuration file (typically <I>~/.ptpython/config.py</I>), which requires some familiarity with Python scripting.</li>


title: INSTALLATION
content:
To install <I>ptpython3</I>, you typically use the Python package installer <I>pip</I>:<br><br><b><code>pip install ptpython</code></b><br><br>Ensure you are using <I>pip</I> associated with your Python 3 installation (e.g., <I>pip3</I> if multiple Python versions are present). After installation, the command will usually be available as <I>ptpython</I> or <I>ptpython3</I>.


title: CONFIGURATION
content:
Customization of <I>ptpython3</I> is handled through a Python configuration file, usually located at <I>~/.ptpython/config.py</I>. This file allows users to define custom key bindings, set default styles, enable or disable features, and configure how autocompletion works. For instance, you can enable Vi mode by default, change color schemes, or load specific modules on startup by editing this file.


title: INTERACTIVE FEATURES
content:
<I>ptpython3</I> significantly enhances the interactive Python experience with several key features:<br><li><B>Syntax Highlighting</B>: Code is colored in real-time as you type, making it easier to read and spot errors.</li><br><li><B>Autocompletion</B>: Provides intelligent, context-aware suggestions for module names, functions, methods, and variables.</li><br><li><B>Multiline Editing</B>: Seamlessly write and execute code blocks spanning multiple lines, with correct indentation.</li><br><li><B>Key Bindings</B>: Offers both Emacs and Vi key bindings, catering to different user preferences.</li><br><li><B>Paste Mode</B>: Helps prevent unexpected indentation issues when pasting code from external sources.</li>


title: HISTORY
content:
<I>ptpython3</I> was developed by Jonathan Slenders, the creator of the popular <I>prompt_toolkit</I> library, which forms its core. It emerged as a natural application of <I>prompt_toolkit</I>'s capabilities, aiming to provide a modern, highly interactive Python REPL that leverages all the advanced terminal features offered by its underlying library. While IPython gained popularity for its rich features, <I>ptpython</I> (and thus <I>ptpython3</I>) offers a lighter, more focused alternative, prioritizing speed and advanced terminal interaction.


title: SYNOPSIS
content:
<b>pup</b> [<I>options</I>] [<I>selector</I>] [<I>attribute</I>]<br><b>pup</b> [<I>options</I>] --file <I>filename</I>


title: PARAMETERS
content:
<b>-i, --input <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an input HTML file. If omitted, <i>pup</i> reads from standard input.<br><br><b>-o, --output <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write output to a specified file instead of standard output.<br><br><b>-c, --color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable syntax highlighting for HTML output, useful for viewing on terminals.<br><br><b>-p, --pretty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty-print HTML output with proper indentation and newlines.<br><br><b>--attr <attribute></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extract the value of a specific attribute (e.g., 'href', 'src') from the selected elements.<br><br><b>--text</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extract only the inner text content of the selected elements, stripping all HTML tags.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output selected elements as a JSON array, with each element represented as an object.<br><br><b>--xml</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output selected elements formatted as XML.<br><br><b>--html</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output selected elements as HTML (this is the default behavior).<br><br><b>--plain</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output selected elements as plain text, similar to --text but potentially with different formatting.<br><br><b>--raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the raw HTML of selected elements without any reformatting.<br><br><b>--pre</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserve leading whitespace in text output.<br><br><b>--file <filename></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read HTML from the specified filename, an alternative to piping input or using -i.<br><br><b>-v, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the current version information of <i>pup</i>.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the help message and exit.<br><br>


title: DESCRIPTION
content:
<i>pup</i> is a command-line tool designed for processing HTML content, analogous to how <i>jq</i> handles JSON. It parses HTML documents, allowing users to select elements using standard CSS selectors, and then extract, modify, or reformat the matched content. Its primary use cases include lightweight web scraping, extracting specific data from HTML files or web pages, and transforming HTML into other formats like plain text, JSON, or XML. <i>pup</i> can read HTML from standard input or a specified file, and its output can be piped to other command-line utilities for further processing. It simplifies complex HTML parsing tasks by providing a familiar CSS selector syntax, making it accessible for developers and system administrators alike.


title: CAVEATS
content:
<b>Parsing Malformed HTML</b>: While <i>pup</i> is robust, extremely malformed or non-standard HTML might not parse as expected, leading to incomplete or incorrect extractions.<br><b>Resource Usage</b>: For very large HTML documents, <i>pup</i> might consume significant memory as the entire document is loaded for parsing.<br><b>Dynamic Content</b>: <i>pup</i> processes static HTML content. It cannot execute JavaScript or interact with dynamic content loaded after the initial page load, unlike headless browser solutions.


title: COMMON USAGE PATTERN
content:
<i>pup</i> is frequently used in conjunction with <i>curl</i> or <i>wget</i> to fetch web pages, then pipe their HTML output directly into <i>pup</i> for extraction. For example:<br><code><b>curl</b> <I>https://example.com</I> | <b>pup</b> 'div.content a' attr href</code><br>This command fetches the content of <i>example.com</i>, pipes it to <i>pup</i>, selects all <code>&lt;a&gt;</code> tags within elements with class <code>content</code>, and extracts their <code>href</code> attributes.


title: SELECTOR SPECIFICITY
content:
<i>pup</i> supports a wide range of CSS selectors, from simple tag names and classes to more complex attribute selectors, pseudo-classes (like <code>:first-child</code>, <code>:nth-of-type</code>), and combinators (e.g., <code>&gt;</code> for direct children, <code>+</code> for adjacent siblings), allowing for precise targeting of HTML elements within a document.


title: HISTORY
content:
<i>pup</i> was created by Eric Chiang and is written in <i>Go</i>, a programming language known for its efficiency and concurrency. Its development aimed to provide a lightweight, self-contained tool for HTML manipulation that could integrate seamlessly into command-line workflows, mirroring the success of <i>jq</i> for JSON. The choice of <i>Go</i> facilitates easy cross-platform compilation and deployment, making <i>pup</i> a portable and robust utility for developers and system administrators needing to parse HTML without the overhead of scripting languages or full-fledged browser environments.


title: SYNOPSIS
content:
<b>pve-firewall</b> <i>&lt;command&gt;</i> [<i>&lt;options&gt;</i>]<br><br>Common commands include <i>start</i>, <i>stop</i>, <i>reload</i>, <i>status</i>, <i>set</i>, <i>get</i>, <i>block-ip</i>, <i>unblock-ip</i>, <i>log</i>, <i>aliases</i>, <i>ipset</i>, <i>securitygroup</i>, and <i>rule</i>. Specific options and arguments depend on the chosen <i>&lt;command&gt;</i>.


title: DESCRIPTION
content:
The <b>pve-firewall</b> command provides a high-level interface for managing the integrated firewall within Proxmox Virtual Environment (PVE). It abstracts the complexities of underlying <i>netfilter</i> (iptables/nftables) rules, allowing users to configure firewall settings at multiple levels: the entire datacenter, individual Proxmox nodes (hosts), and specific virtual machines (VMs) or containers (CTs).<br><br>It supports various features including rule management, security groups, IP sets, aliases, and logging. The firewall ensures network isolation and enhances the security of virtualized environments by controlling ingress and egress traffic. All configurations are stored in the cluster filesystem (<i>pmxcfs</i>), enabling real-time synchronization across all cluster nodes.


title: CAVEATS
content:
Direct manipulation of <i>iptables</i> or <i>nftables</i> rules can interfere with <b>pve-firewall</b>'s operation and is generally discouraged unless you understand its internals. Using <i>block-ip</i> indiscriminately can lead to network lockout. The firewall relies on the <i>pve-firewall</i> service running correctly on all nodes.


title: FIREWALL LEVELS
content:
<b>pve-firewall</b> allows rules to be applied at three distinct levels:<br><b>Datacenter Level:</b> Global rules applied to all nodes and VMs/CTs in the cluster.<br><b>Host Level:</b> Rules specific to an individual Proxmox node, affecting all traffic to/from that host.<br><b>VM/CT Level:</b> Rules applied directly to a specific virtual machine or container, controlling its individual network traffic.


title: CONFIGURATION STORAGE
content:
All <b>pve-firewall</b> configurations, including rules, IP sets, and aliases, are stored within the <i>pmxcfs</i> (Proxmox Cluster File System). This ensures that configurations are consistent across all nodes in a Proxmox VE cluster and allows for live updates without requiring manual synchronization.


title: HISTORY
content:
The integrated firewall was introduced in Proxmox VE 3.4 (released in 2015) to provide a centralized and easy-to-use firewall solution for virtualized environments. Initially built upon <i>iptables</i>, its capabilities have evolved to support <i>nftables</i> and integrate seamlessly with new Proxmox VE features, constantly enhancing network security management.


title: SYNOPSIS
content:
`pw-play [options] <file> [file...]<br><i>Example:</i> `pw-play -V 0.5 -l my_song.wav`<br>This plays `my_song.wav` at half volume and loops it continuously.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output for detailed operation information.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the `pw-play` version information.<br><br><b>-d <duration>, --duration=<duration></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the playback duration in seconds.<br><br><b>-p <position>, --position=<position></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts playback from a specific position in seconds within the file.<br><br><b>-o <offset>, --offset=<offset></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips the initial offset in seconds from the beginning of the file.<br><br><b>-l, --loop</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loops the audio playback continuously until manually stopped.<br><br><b>-V <volume>, --volume=<volume></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the initial playback volume (e.g., 0.5 for half volume).<br><br><b>-c <channels>, --channels=<channels></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired number of audio channels for playback.<br><br><b>-r <rate>, --rate=<rate></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired sample rate for playback.<br><br><b>-m <map>, --channel-map=<map></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom channel map (e.g., <i>FL,FR,FC</i> for front left, front right, front center).<br><br><b>-F <format>, --format=<format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the sample format (e.g., <i>S16LE</i> for 16-bit signed little-endian, <i>F32LE</i> for 32-bit float little-endian).<br><br><b>-n <name>, --node-name=<name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns a specific name to the PipeWire node created for this playback.<br><br><b>-N <name>, --node-description=<name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a description for the PipeWire node.<br><br><b>-P <property>=<value>, --property=<property>=<value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows setting arbitrary PipeWire node properties (e.g., <i>node.target=my_sink</i>).<br><br><b>-L <latency>, --latency=<latency></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the target latency for the audio stream in seconds.<br><br><b>-q, --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses statistical output during playback.<br><br>


title: DESCRIPTION
content:
`pw-play` is a command-line utility designed to play audio files through the <i>PipeWire</i> multimedia framework. It acts as a client to the PipeWire sound server, providing low-latency and efficient audio playback. This command is part of the broader PipeWire ecosystem, which aims to provide a modern solution for audio and video processing, replacing older systems like <i>PulseAudio</i> and <i>JACK</i>.<br><br>Users can specify one or more audio files for playback. `pw-play` automatically handles the connection to the PipeWire daemon and sets up the necessary audio streams. It supports various audio formats, leveraging underlying libraries such as <i>libsndfile</i>. Its integration with PipeWire allows it to participate in the PipeWire graph, enabling complex routing and processing setups when needed, although its primary function is simple playback. It's a fundamental tool for testing audio output and playing media in environments where PipeWire is the active sound server.


title: CAVEATS
content:
`pw-play` requires a running <i>PipeWire</i> daemon to function correctly. If PipeWire is not active, the command will fail to connect and play audio.<br><br>The ability to play specific audio file formats depends on the underlying libraries and PipeWire modules installed, primarily <i>libsndfile</i> for common formats like WAV, AIFF, FLAC.<br><br>Playback quality and output device selection are managed by PipeWire's routing capabilities, which might require further configuration within PipeWire for advanced setups.


title: EXIT STATUS
content:
`pw-play` typically exits with a status of 0 upon successful completion of playback. A non-zero exit status usually indicates an error, such as failure to connect to the PipeWire daemon, an invalid file path, or an unsupported file format.


title: ENVIRONMENT VARIABLES
content:
While `pw-play` itself doesn't typically rely on specific environment variables for its core functionality, the underlying PipeWire library and daemon might be influenced by variables like <i>PIPEWIRE_DEBUG</i> for debugging purposes, or <i>PIPEWIRE_LATENCY</i> for global latency adjustments. However, these are generally not specific to `pw-play`'s direct usage.


title: HISTORY
content:
<i>PipeWire</i>, and consequently `pw-play`, emerged as a modern multimedia framework for Linux, aiming to handle audio and video streams more efficiently and securely than previous solutions like <i>PulseAudio</i> for desktop audio and <i>JACK</i> for professional audio. Development began around 2017, driven by the need for better low-latency audio/video capabilities, especially for Wayland compositors and Flatpak applications.<br><br>`pw-play` was introduced as a simple, native utility for basic audio playback within this new ecosystem, providing a familiar command-line interface for playing sound files while leveraging PipeWire's advanced graph capabilities for routing and processing. It represents PipeWire's commitment to providing robust and user-friendly tools for multimedia handling.


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help options and usage information.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version of <i>pw-profiler</i>.<br><br><b>-i, --input FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the input file containing profiling data. If omitted, input is read from standard input (stdin).<br><br><b>-o, --output FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output file to write the processed data. If omitted, output is written to standard output (stdout).<br><br><b>-m, --mode MODE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the output mode for analysis. Possible modes are 'graph' (default), 'dump', and 'stats'.<br>  <br><b>graph</b>: Visualizes the execution flow as a call graph.<br><b>dump</b>: Provides a raw, chronological dump of profiling events.<br><b>stats</b>: Shows aggregated statistics of events.<br><br><b>-j, --json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the results in JSON format. This option overrides the <i>--mode</i> setting.<br><br><b>-p, --pretty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pretty print the JSON output, making it more readable with indentation.<br><br><b>-t, --time-unit UNIT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the time unit for 'stats' mode. Options: 'ns' (nanoseconds), 'us' (microseconds, default), 'ms' (milliseconds), 's' (seconds).<br><br><b>-f, --format FORMAT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the format for 'dump' mode. Options: 'text' (default) and 'csv' (comma-separated values).<br><br><b>-s, --sort FIELD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the field to sort by in 'stats' mode. Options: 'time', 'count', 'avg' (average time).<br><br><b>-r, --reverse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reverse the sort order in 'stats' mode (descending instead of ascending).<br><br><b>-n, --limit N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the number of entries displayed in 'stats' mode to the top N entries.<br><br>


title: DESCRIPTION
content:
<i>pw-profiler</i> is a PipeWire utility for analyzing performance and timing data generated by PipeWire components. It can read profiling dumps, typically captured from <i>pw-top</i> or other PipeWire tools, and present them in various formats like call graphs, detailed event dumps, or aggregated statistics. This tool is invaluable for debugging performance issues, identifying bottlenecks, and understanding the execution flow within the PipeWire graph, helping developers and system administrators optimize multimedia processing and ensure low-latency multimedia operations.


title: CAVEATS
content:
<ul><li><i>pw-profiler</i> analyzes <i>pre-recorded</i> profiling data; it does not profile live PipeWire sessions directly.</li><li>The quality and usefulness of the output depend heavily on the verbosity and type of profiling data collected by the source (e.g., <i>pw-top</i>'s dump).</li><li>Interpreting the output, especially call graphs and detailed dumps, often requires a good understanding of PipeWire's internal architecture and component interactions.</li></ul>


title: USAGE WITH <I>PW-TOP</I>
content:
Profiling data for <i>pw-profiler</i> can often be captured from <i>pw-top</i>, PipeWire's top-like graph and performance monitor. You can redirect <i>pw-top</i>'s output or use its profiling dump feature (if available) to a file, then feed that file into <i>pw-profiler</i>.<br>Example: <code>pw-top --dump-profile > profile.txt</code> followed by <code>pw-profiler -i profile.txt -m graph</code>.


title: UNDERSTANDING OUTPUT MODES
content:
The <i>--mode</i> option provides different perspectives on the profiling data:<br><br><b>Graph Mode</b>: Generates a hierarchical view of function calls and their timings, useful for identifying call paths and latencies within the PipeWire processing flow.<br><br><b>Dump Mode</b>: Provides a raw chronological list of profiling events, valuable for detailed event sequence analysis and debugging specific timing issues.<br><br><b>Stats Mode</b>: Aggregates profiling data, showing total time spent, call counts, and average times for each profiled function or component, excellent for quick performance overviews and identifying top bottlenecks.


title: HISTORY
content:
<i>pw-profiler</i> is an integral part of the PipeWire project, which was initially developed by Wim Taymans at Red Hat and publicly announced in 2017. Designed as a modern low-latency, high-performance multimedia server for Linux, PipeWire aims to handle audio, video, and hardware access seamlessly. The <i>pw-profiler</i> utility was introduced as an essential debugging and optimization tool, evolving with the PipeWire framework itself, to help developers understand and fine-tune its complex graph processing and performance characteristics.


title: PARAMETERS
content:
<b>--verbose, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase verbosity.<br><br><b>--quiet, -q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decrease verbosity.<br><br><b>--capture=no, -s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable capturing of stdout/stderr during test execution.<br><br><b>--exitfirst, -x</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit instantly on first error or failed test.<br><br><b>--last-failed, --lf</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rerun only the tests that failed in the previous run.<br><br><b>--failed-first, --ff</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run previously failed tests first, then the rest.<br><br><b>--durations=N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the N slowest test durations (or 0 for all).<br><br><b>-k EXPRESSION</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only run tests whose names match the given substring expression. Example: <b>-k "MyClass and not method"</b>.<br><br><b>-m MARKEXPR</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only run tests matching the given marker expression. Example: <b>-m "slow or webtest"</b>.<br><br><b>--strict-markers</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enforce that markers used are registered in <b>pytest.ini</b> or <b>pyproject.toml</b>.<br><br><b>--collect-only</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dry run: collect tests without executing them.<br><br><b>-r CHARS</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show extra test summary info for failed, passed, skipped, xfailed, xpassed tests. Example: <b>-r sfE</b>.<br><br><b>--numprocesses=N, -n N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Distribute tests across N processes (requires <i>pytest-xdist</i> plugin).<br><br>


title: DESCRIPTION
content:
<br><i>pytest</i> is a powerful and popular Python testing framework designed for writing simple, readable, and scalable tests. It emphasizes developer productivity by providing a low-boilerplate approach to test writing compared to Python's built-in <i>unittest</i> module. Key features include automatic test discovery, a rich plugin architecture, a flexible fixture system for managing test setup and teardown, and assert rewriting for more informative assertion failures without special syntax.<br><br><i>pytest</i> tests are typically written as simple Python functions that start with <b>test_</b> within files that start or end with <b>test_</b>. It supports parametrizing tests, allowing a single test function to be run with various sets of inputs, reducing code duplication. Its extensive plugin ecosystem further enhances its capabilities, offering integrations for coverage reporting, parallel test execution (<i>pytest-xdist</i>), mock objects, and more. Used widely in industry and open-source projects, <i>pytest</i> facilitates writing clear, maintainable, and high-quality test suites for applications of all sizes.


title: CAVEATS
content:
<br>While <i>pytest</i> is generally straightforward, users should be aware of a few points:<br><b>Dependency Management:</b> <i>pytest</i> and its plugins must be installed via pip (e.g., <b>pip install pytest</b>). Ensure your testing environment has the necessary packages.<br><b>Test Discovery Nuances:</b> <i>pytest</i> has specific rules for test discovery (e.g., <b>test_*.py</b> files, <b>test_*</b> functions/methods). Deviating from these conventions requires explicit configuration.<br><b>Overuse of Fixtures:</b> While fixtures are powerful, overly complex or deeply nested fixtures can sometimes make tests harder to read and debug.<br><b>Parallelization Setup:</b> For large test suites, parallel execution via <i>pytest-xdist</i> is highly beneficial but requires an additional <b>pip install pytest-xdist</b>.


title: TEST DISCOVERY RULES
content:
By default, <i>pytest</i> finds tests in <b>test_*.py</b> or <b>*_test.py</b> files, functions starting with <b>test_</b>, and methods starting with <b>test_</b> inside classes not derived from <i>unittest.TestCase</i> (unless specified).


title: FIXTURE SYSTEM
content:
<i>pytest</i> fixtures provide a powerful and flexible way to set up and tear down test environments. They are defined as functions and can be shared across tests, modules, or even sessions, promoting code reuse and clear separation of concerns.


title: PLUGIN ECOSYSTEM
content:
A core strength of <i>pytest</i> is its extensive plugin system, allowing developers to extend its functionality easily. Popular plugins include <i>pytest-cov</i> (for coverage), <i>pytest-mock</i> (for mocking), and <i>pytest-html</i> (for HTML reports), significantly enhancing testing workflows.


title: HISTORY
content:
<br><i>pytest</i> originated in 2004 as `py.test`, part of the larger `py` library by Holger Krekel. It quickly gained traction for its simplicity, extensibility, and less boilerplate-heavy approach compared to its contemporaries like Python's `unittest`. Over the years, it evolved into a standalone project, shedding the `py.` prefix to become simply `pytest`. Its adoption significantly increased due to its powerful fixture system, assert rewriting, and a vibrant plugin ecosystem, making it the de-facto standard for Python testing for many developers and organizations by the 2010s. Continuous development ensures it remains a modern and robust testing solution.


title: SYNOPSIS
content:
<b>qm</b> <I>&lt;subcommand&gt;</I> <I>[&lt;vmid&gt;]</I> <I>[&lt;options&gt;]</I> <I>[&lt;args&gt;]</I>


title: PARAMETERS
content:
<b>create &lt;vmid&gt; &lt;options&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new KVM virtual machine with specified VMID and configuration options.<br><br><b>start &lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the specified virtual machine.<br><br><b>stop &lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Immediately stops the specified virtual machine, similar to pulling the power plug.<br><br><b>shutdown &lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gracefully shuts down the specified virtual machine (requires guest agent or ACPI).<br><br><b>status &lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current status of a virtual machine (e.g., running, stopped, paused).<br><br><b>list</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all virtual machines and containers on the system with their status and other details.<br><br><b>config &lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current configuration of a virtual machine.<br><br><b>set &lt;vmid&gt; &lt;options&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Modifies one or more configuration options for a virtual machine.<br><br><b>migrate &lt;vmid&gt; &lt;target_node&gt; &lt;options&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Migrates a virtual machine to another Proxmox VE node in the cluster.<br><br><b>backup &lt;vmid&gt; &lt;options&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a backup of the specified virtual machine to a configured storage.<br><br><b>restore &lt;vmid&gt; &lt;filepath&gt; &lt;options&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restores a virtual machine from a backup file.<br><br><b>destroy &lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Permanently deletes a virtual machine and all its associated data.<br><br><b>clone &lt;vmid&gt; &lt;new_vmid&gt; &lt;options&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a clone of an existing virtual machine.<br><br>


title: DESCRIPTION
content:
<I>qm</I> is the primary command-line utility for managing virtual machines (KVM) and Linux containers (LXC) within a Proxmox Virtual Environment (PVE) installation. It provides a comprehensive set of subcommands to perform almost any administrative task related to VMs and containers, including creation, starting, stopping, configuration, migration, backup, and restoration. <br><br>As a high-level wrapper around QEMU/KVM and LXC, <I>qm</I> simplifies complex operations, interacting directly with the underlying Proxmox API and services. It's an indispensable tool for administrators managing Proxmox VE servers, offering detailed control over virtualized resources, storage, and networking.


title: CAVEATS
content:
The <I>qm</I> command is specific to Proxmox Virtual Environment (PVE) installations and is not a standard Linux command found on general-purpose distributions. It requires a PVE installation to be present and typically needs root privileges or appropriate sudo permissions to execute. Incorrect usage, especially with subcommands like <I>destroy</I> or <I>set</I>, can lead to data loss or system instability.


title: VMID (VIRTUAL MACHINE ID)
content:
Most <I>qm</I> subcommands require a <B>VMID</B>, which is a unique integer identifier for each virtual machine or container in Proxmox VE. These IDs typically range from 100 to 999999999, and are used to refer to a specific VM or container when executing commands.


title: ACCESSING MANPAGES
content:
For detailed information on any specific subcommand and its options, use <B>qm help &lt;subcommand&gt;</B> or consult the comprehensive manpage using <B>man qm</B> on a Proxmox VE system.


title: HISTORY
content:
The <I>qm</I> command is an integral part of Proxmox Virtual Environment, a Debian-based Linux distribution for virtualization. Proxmox VE was first released in 2007, and <I>qm</I> has been its primary command-line interface for managing KVM-based virtual machines since its early versions. Its development closely follows the evolution of Proxmox VE, incorporating new features and improvements with each major release, reflecting advancements in QEMU/KVM and LXC technologies. It serves as a user-friendly wrapper for the complex underlying virtualization commands and APIs.


title: PARAMETERS
content:
<b><I>vmid</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The numeric ID of the existing virtual machine or container to clone.<br><br><b><I>newid</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The numeric ID to assign to the new virtual machine or container.<br><br><b>--full <I>boolean</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to 'true', perform a full copy of all disk images, making the new VM/container independent. Defaults to 'false' (linked clone) if not specified.<br><br><b>--storage <I>storage</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target storage where the new VM/container's disk images will be placed. If not specified, the original storage is used for full clones, or the same storage as the original for linked clones.<br><br><b>--name <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign a human-readable name to the newly created virtual machine or container.<br><br><b>--description <I>description</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add an arbitrary descriptive text for the new VM/container.<br><br><b>--format <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the disk image format for the cloned disks (e.g., 'qcow2', 'raw', 'vmdk'). Applicable primarily for full clones.<br><br><b>--target-node <I>node</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target Proxmox VE node where the new VM/container should be created. By default, it's created on the same node as the source VM/container.<br><br><b>--pool <I>poolid</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assign the new VM/container to a specific resource pool.<br><br><b>--bwlimit <I>integer</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limit the bandwidth for disk operations during the cloning process, specified in KB/s.<br><br><b>--snapname <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a specific snapshot of the source VM/container as the basis for the clone instead of its current state.<br><br>


title: DESCRIPTION
content:
The <b>qm-clone</b> command in Proxmox VE is used to create a new virtual machine or container (LXC) by replicating an existing one. It allows for two main types of cloning: <br><i>full clones</i> and <i>linked clones</i>. A <i>full clone</i> creates an independent, complete copy of all disk images, meaning the new VM/container is entirely separate from its source. A <i>linked clone</i>, on the other hand, creates a new VM/container that shares the original's base disk image, storing only changes in a new delta image (also known as a Copy-on-Write, or COW, clone). Linked clones save disk space and are faster to create but maintain a dependency on the original VM/container's disk images. This command is essential for quickly deploying multiple similar instances or setting up test environments based on pre-configured setups.


title: CAVEATS
content:
When using <i>linked clones</i> (the default behavior if `--full` is not specified), the cloned VM/container is dependent on the original VM/container's base disk image. If the original VM/container or its base disk is deleted, moved, or corrupted, the linked clone will become unusable. For production environments or completely independent instances, <i>full clones</i> are generally recommended.


title: CLONING TYPES
content:
There are two main types of cloning:<br><b>Full Clone:</b> Creates a complete, independent copy of the VM's disk. This takes longer and consumes more disk space but ensures the new VM has no dependency on the original. Use <code>--full 1</code> for this type.<br><b>Linked Clone:</b> Creates a Copy-on-Write (CoW) snapshot. The new VM shares the base disk with the original, only storing changes. This is much faster and saves disk space but creates a dependency. This is the default behavior if <code>--full</code> is not specified.


title: COMMON USAGE
content:
A common use case for <b>qm-clone</b> is to create a 'template' VM or container. Once a base operating system installation is configured, it can be rapidly deployed into new instances by cloning it multiple times for different services or development environments, significantly reducing setup time.


title: HISTORY
content:
The <b>qm-clone</b> command is an integral part of the Proxmox VE command-line interface (CLI), specifically designed to manage QEMU/KVM virtual machines. Proxmox VE, an open-source server virtualization management solution, has continually evolved its CLI tools since its inception in 2007. The cloning functionality has been a core feature, reflecting the need for rapid deployment and efficient resource utilization in virtualized environments. It abstracts the underlying QEMU/KVM and various storage backends (like LVM, ZFS, Ceph) operations, providing a user-friendly way to replicate virtual instances.


title: PARAMETERS
content:
<b><i>vmid</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID (integer) of the virtual machine whose configuration is to be displayed.<br><br><b>--full</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the full configuration, including default values that are not explicitly set in the VM's configuration file.<br><br><b>--type <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show only configuration properties of a specific type, such as 'net' for network interfaces, 'disk' for storage devices, 'cpu', 'memory', or 'boot'.<br><br><b>--raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the raw configuration data. This format is typically less human-readable but can be useful for scripting or internal system analysis.<br><br><b>--pretty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Format the output for better human readability. This is often the default behavior when not specifying --raw.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress error messages for non-existent VMIDs or other non-critical issues, useful in scripts.<br><br>


title: DESCRIPTION
content:
<i>qm-config</i> is a utility within the Proxmox VE ecosystem designed to display the current configuration settings of a specific QEMU/KVM virtual machine. It retrieves and formats various parameters such as CPU, memory, network interfaces, disk drives, boot order, and other hardware or system-level settings associated with a VM identified by its unique ID (<b>VMID</b>). This command is crucial for administrators to quickly review, troubleshoot, or verify a VM's setup without needing to access the Proxmox web interface or configuration files directly. It provides a human-readable output, which can be further refined using various options to show full details, specific sections, or raw data.


title: CAVEATS
content:
This command is specific to Proxmox Virtual Environment (PVE) installations and is not a general Linux utility found on standard distributions. It requires a Proxmox VE environment to function correctly. The command's functionality and options are tightly coupled with the Proxmox VM management system.


title: OUTPUT FORMAT
content:
By default, <i>qm-config</i> outputs configuration in a clear, human-readable key-value pair format. When using the <b>--raw</b> option, the output is often a direct dump of the internal configuration, which might be less structured but valuable for advanced debugging or programmatic parsing.


title: VMID REQUIREMENT
content:
A valid <b>VMID</b> is mandatory for <i>qm-config</i> to operate. Without a valid and existing virtual machine identifier, the command will return an error indicating a missing or invalid virtual machine.


title: HISTORY
content:
<i>qm-config</i> is an integral part of the Proxmox Virtual Environment (PVE) management toolset, developed by Proxmox Server Solutions GmbH. It emerged as part of the <b>qm</b> (QEMU/KVM manager) utility to provide command-line access to VM configurations, complementing the robust web-based user interface. Its development has mirrored the evolution of Proxmox VE itself, focusing on robust and user-friendly server virtualization management capabilities.


title: PARAMETERS
content:
<b><vmid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID for the new virtual machine (100-999999999).<br><br><b>--name <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the VM's descriptive name.<br><br><b>--ostype <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the guest operating system type (e.g., <i>l26</i> for Linux, <i>win10</i> for Windows).<br><br><b>--memory <integer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the amount of RAM in MiB allocated to the VM.<br><br><b>--cores <integer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the number of CPU cores.<br><br><b>--cpu <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the CPU type (e.g., <i>host</i> for host CPU features, <i>kvm64</i>).<br><br><b>--net<id> <key=value,...></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures a network device (e.g., <i>virtio,bridge=vmbr0</i>).<br><br><b>--scsi<id> <key=value,...></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a SCSI disk device (e.g., <i>storage:size=32G</i>).<br><br><b>--ide<id> <key=value,...></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines an IDE disk device.<br><br><b>--sata<id> <key=value,...></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a SATA disk device.<br><br><b>--virtio<id> <key=value,...></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a VirtIO block device.<br><br><b>--bootdisk <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies which disk to boot from (e.g., <i>scsi0</i>, <i>ide0</i>).<br><br><b>--boot <order></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the boot order for devices (e.g., <i>cdn</i> for CD-ROM, Disk, Network).<br><br><b>--template <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks this VM as a template, preventing it from being started directly.<br><br><b>--description <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a textual description or note for the VM.<br><br><b>--onboot <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines if the VM should start automatically when the host boots (0=no, 1=yes).<br><br><b>--agent <integer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables the QEMU guest agent (0=disabled, 1=enabled).<br><br><b>--bios <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the BIOS type (e.g., <i>seabios</i>, <i>ovmf</i> for UEFI).<br><br><b>--vga <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the virtual graphics adapter type (e.g., <i>std</i>, <i>qxl</i>).<br><br><b>--ciuser <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cloud-init: Sets the default username for cloud-init.<br><br><b>--sshkeys <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Cloud-init: Provides SSH public keys for the default user.<br><br>


title: DESCRIPTION
content:
The <i>qm-create</i> command is a fundamental utility within the Proxmox Virtual Environment (PVE) for provisioning new KVM (Kernel-based Virtual Machine) instances from the command line. It enables administrators to define the essential configuration parameters for a VM, including its unique virtual ID (VMID), allocated memory, CPU resources, network interfaces, and storage devices. This command is crucial for setting up a VM's infrastructure before an operating system is installed or disk images are imported. It integrates seamlessly with Proxmox's diverse storage backends (such as LVM, ZFS, directory, or Ceph) and network configurations (like virtual bridges), allowing for flexible and powerful VM deployments. While <i>qm-create</i> sets up the VM's hardware configuration, it does not install an operating system; that typically follows via ISO installation or cloud-init. For a comprehensive list of all available options, users should consult the official Proxmox VE documentation or use <b>qm create --help</b>.


title: CAVEATS
content:
Creating a VM only sets up its hardware configuration; it does not install an operating system.<br>Requires a unique VMID that is not already in use across the Proxmox cluster.<br>Disk and network configurations can be complex, necessitating specific syntax and existing storage/network resources.<br>Many advanced options exist, necessitating consultation of official documentation or <b>qm create --help</b> for full details.


title: VMID IMPORTANCE
content:
The <b>VMID</b> is a mandatory, unique identifier for each virtual machine or container in Proxmox, ranging from 100 to 999,999,999. Choosing an appropriate and available VMID is the first step in creating a new VM, as it serves as the primary reference for all subsequent management operations.


title: DISK PROVISIONING VS. ATTACHMENT
content:
When defining disks (e.g., with <i>--scsi0</i>), <i>qm-create</i> can automatically provision and format a new disk image on the specified storage backend with the given size and format. This is distinct from attaching a pre-existing disk image, which is typically done later using the <b>qm set</b> command.


title: CLOUD-INIT AUTOMATION
content:
For guest operating systems supporting <i>cloud-init</i>, <i>qm-create</i> provides specific options like <i>--ciuser</i>, <i>--cipassword</i>, and <i>--sshkeys</i>. These allow for automated initial user setup, network configuration, and script execution upon the VM's first boot, significantly streamlining VM deployment for template-based scenarios.


title: HISTORY
content:
<i>qm-create</i> has been a core component of the Proxmox Virtual Environment since its early versions, evolving to support modern virtualization features like UEFI, hotplugging, diverse storage technologies (e.g., ZFS, Ceph), and advanced CPU types. Its development mirrors the continuous enhancement of Proxmox VE as a robust, open-source hyper-converged platform, offering flexible and powerful command-line management capabilities for KVM guests and being integral to its growth.


title: PARAMETERS
content:
<b>topic</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific Qmail-related command, configuration file, concept, or utility for which documentation is sought (e.g., <I>qmail-send</I>, <I>control-files</I>).<br><br><b>section</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional numerical or descriptive section of the manual to search within (e.g., <I>1</I> for general commands, <I>5</I> for file formats, <I>8</I> for system administration). This helps to narrow down the search if multiple entries exist for the same topic across different manual sections.<br><br>


title: DESCRIPTION
content:
The <I>qm-help</I> command is a specialized utility within the Qmail mail transfer agent (MTA) suite, designed to provide convenient access to its extensive documentation. Rather than being a general system-wide help tool, it focuses exclusively on Qmail-related topics, including commands, configuration files, administration procedures, and conceptual information. It functions much like a tailored <I>man</I> command, allowing users to quickly look up detailed information pertinent to Qmail's operation. Users can specify a particular <I>topic</I> (e.g., <I>qmail-send</I>, <I>qmail-smtpd</I>, <I>control-files</I>) or even a specific <I>manual section</I> along with the topic, similar to how standard man pages are categorized (e.g., section 1 for user commands, section 5 for file formats, section 8 for system administration commands). This integration simplifies the process of understanding and troubleshooting Qmail components by centralizing its documentation.


title: CAVEATS
content:
The <I>qm-help</I> command is specific to installations of the Qmail mail transfer agent. It will not be available or functional on systems that do not have Qmail installed. The quality and completeness of the displayed documentation depend entirely on the Qmail package and its associated documentation files present on the system. It is not a substitute for general Linux command documentation or other system utilities.


title: USAGE CONTEXT
content:
While conceptually similar to the standard <I>man</I> command, <I>qm-help</I> is pre-configured to search paths specific to Qmail's documentation. This streamlines the process of finding Qmail-specific man pages without needing to explicitly specify paths or rely on a globally indexed system that might not always prioritize Qmail documentation. It's especially useful for administrators managing Qmail installations who need quick access to component-specific details.


title: HISTORY
content:
The <I>qm-help</I> command is an integral part of the Qmail suite, a mail transfer agent created by Daniel J. Bernstein (DJB) in the mid-1990s. Qmail gained significant popularity for its focus on security, reliability, and modular design, often cited as a more secure alternative to Sendmail at the time. <I>qm-help</I> was developed alongside the main Qmail components to provide readily accessible, integrated documentation, making it easier for administrators and users to navigate the specifics of Qmail's architecture and configuration. Its design reflects DJB's philosophy of providing complete and well-structured documentation alongside software.


title: PARAMETERS
content:
<b><I>vmid</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required.</i> The unique numeric identifier (e.g., 100, 101) of the virtual machine whose QEMU monitor console you wish to access.<br><br><b>--path <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional.</i> Specifies an alternative Unix socket path for the QEMU monitor. This is rarely used in standard Proxmox setups as the path is automatically derived from the VMID.<br><br><b>--pretty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional.</i> When interacting with the QEMU Machine Protocol (QMP), this option formats the JSON output for improved readability, making it easier to parse.<br><br><b>--raw</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional.</i> Prevents any pretty-printing of output, showing the raw QEMU monitor or QMP output directly. This is particularly useful for scripting purposes or when piping output to other tools.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional.</i> Displays a concise help message for the <b>qm monitor</b> subcommand, outlining its syntax and available options.<br><br>


title: DESCRIPTION
content:
The <b>qm monitor</b> command (part of the Proxmox VE <b>qm</b> utility) provides direct access to the QEMU monitor console of a running virtual machine. This powerful tool allows administrators to execute low-level QEMU commands, offering granular control and detailed insight into the VM's internal state. It's invaluable for advanced diagnostics, debugging, and performing specific operations not typically exposed through the higher-level Proxmox management interface. Users can inspect device status, manage virtual hardware, pause or resume the VM, and even send ACPI signals directly to the guest operating system. Understanding QEMU monitor commands is crucial for effective use.


title: CAVEATS
content:
Connecting to the QEMU monitor requires the VM to be running. Direct interaction with the QEMU monitor involves low-level commands that, if misused, can potentially corrupt the VM state or cause unexpected behavior. It is essential to have a solid understanding of QEMU monitor commands before using this utility for critical operations. This command bypasses higher-level Proxmox safeguards, so exercise caution.


title: INTERACTING WITH THE QEMU MONITOR
content:
Once connected via <b>qm monitor</b>, you will be presented with a QEMU monitor prompt (e.g., (qemu)). You can then type various QEMU monitor commands (Human Monitor Protocol - HMP). Common commands include:<br><b>info status</b> (VM power state)<br><b>info block</b> (disk images)<br><b>info network</b> (network devices)<br><b>stop</b> (pause VM)<br><b>cont</b> (resume VM)<br><b>system_powerdown</b> (graceful shutdown)<br><b>quit</b> (exit monitor, but VM keeps running)<br><br>For programmatic interaction, you can also issue QEMU Machine Protocol (QMP) commands, which communicate using JSON. These are typically prefixed with {'execute': ...}.


title: USAGE SCENARIOS
content:
<b>qm monitor</b> is frequently used for:<br>Troubleshooting guest OS boot issues or unresponsive VMs.<br>Inspecting virtual hardware configuration details.<br>Injecting commands or events that are not available through standard <b>qm</b> commands.<br>Debugging device passthrough configurations.<br>Performing live migrations or complex storage operations at a low level.


title: HISTORY
content:
The <b>qm monitor</b> command is an integral part of the Proxmox Virtual Environment (PVE) management suite, which began its development around 2007. As a core component for advanced VM administration and debugging, it was integrated early into the <b>qm</b> utility to provide administrators with direct, low-level access to the underlying QEMU processes, leveraging QEMU's built-in monitor capabilities for diagnostics and control.


title: PARAMETERS
content:
<b><i>vmid</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ID of the virtual machine or container whose disk is to be moved.<br><br><b><i>disk</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The identifier of the disk to move. This can be a device name (e.g., <i>scsi0</i>, <i>ide0</i>, <i>virtio0</i>) or the full disk path (e.g., <i>vm-100-disk-0</i>).<br><br><b><i>storage</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ID of the target storage to which the disk will be moved.<br><br><b><b>--delete</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <i>true</i>, the original disk will be automatically deleted from its source storage after a successful move operation. Default is <i>false</i>.<br><br><b><b>--format</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired disk format for the new disk on the target storage (e.g., <i>raw</i>, <i>qcow2</i>, <i>vmdk</i>). If not specified, the original format is maintained if supported by the target storage, or a default is chosen.<br><br><b><b>--node</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target node in a Proxmox cluster where the disk should be moved to. Useful when moving disks between nodes while staying on the same storage type (e.g., shared storage).<br><br><b><b>--sparse</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <i>true</i>, enables sparse allocation for the new disk on the target storage, meaning only used blocks are allocated, which can save storage space. This is mainly applicable to <i>qcow2</i> and <i>raw</i> formats. Default is <i>false</i>.<br><br><b><b>--target-disk</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a new disk ID for the moved disk on the target VM (e.g., <i>scsi1</i> instead of <i>scsi0</i>). If not specified, the original disk ID is used.<br><br><b><b>--target-storage</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for the main <i>&lt;storage&gt;</i> argument.<br><br><b><b>--skip-latest-backup</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <i>true</i>, skips the check for the latest backup before moving the disk. Use with caution as this may bypass important data integrity checks.<br><br>


title: DESCRIPTION
content:
The <b>qm-move-disk</b> command is a subcommand of <b>qm</b>, the Proxmox VE (Virtual Environment) virtual machine management tool. It is designed to migrate virtual machine or container disks from one storage location to another within a Proxmox VE cluster or on a standalone node. This command is essential for optimizing storage utilization, improving VM performance by moving to faster storage, or consolidating disks. It handles the complete process of copying the disk data to the target storage, updating the VM's configuration to point to the new disk location, and optionally deleting the original disk. Additionally, <b>qm-move-disk</b> can perform disk format conversions during the migration, such as converting from <i>raw</i> to <i>qcow2</i>.


title: CAVEATS
content:
<ul><li>The virtual machine or container must be <b>stopped</b> for a clean and safe disk move operation, especially for attached disks that are actively in use (e.g., system disks). Moving a live attached disk can lead to data corruption or inconsistencies.</li><br><li>Ensure the target storage has <b>sufficient free space</b> for the new disk.</li><br><li>Disk format conversion and data copying can be a <b>time-consuming process</b>, depending on the disk size, network bandwidth, and I/O performance of the storage systems.</li><br><li>Using the <b>--delete</b> option is irreversible. Always verify that the disk move was successful before deleting the original disk, especially if not using this option and performing manual cleanup.</li></ul>


title: OFFLINE OPERATION STRONGLY RECOMMENDED
content:
For maximum data integrity and to prevent corruption, it is highly recommended to shut down the virtual machine or container before attempting to move its disks using <b>qm-move-disk</b>. This ensures that no data is being written to the disk during the migration process, guaranteeing a consistent copy.


title: SUPPORT FOR VARIOUS STORAGE TYPES
content:
The <b>qm-move-disk</b> command is compatible with a wide range of Proxmox storage types, including but not limited to LVM, LVM-Thin, ZFS, directory-based storage, CephFS, NFS, and iSCSI. The specific features available, such as format conversion or sparse allocation, may depend on the capabilities of both the source and target storage systems.


title: HISTORY
content:
<b>qm-move-disk</b> is a crucial subcommand within the Proxmox VE software suite, which has been under continuous development since its initial release in 2008. As Proxmox VE evolved to support diverse storage backends and advanced clustering features, the <b>qm</b> command and its disk management functionalities, including <b>move-disk</b>, have been steadily refined. This evolution addresses the growing need for dynamic and flexible storage reconfiguration, performance optimization, and robust data management in modern virtualized environments.


title: SEE ALSO
content:
qm(1) - Proxmox VE Qemu/KVM Virtual Machine management tool, pct(1) - Proxmox VE LXC Container management tool, qm disk list(1) - List disks attached to a VM, qm rescan(1) - Rescan for available disks, pvesm(1) - Proxmox VE storage manager CLI


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID of the virtual machine whose disk is to be moved.<br><br><b><i>&lt;diskid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The identifier of the disk to move (e.g., <b>scsi0</b>, <b>ide0</b>, <b>virtio0</b>). This must match the disk ID in the VM's configuration.<br><br><b><i>&lt;target-storage&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the Proxmox storage pool or backend where the disk should be moved.<br><br><b><b>--bwlimit</b> <i>&lt;integer&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the bandwidth for the disk move operation in KiB/s. Useful to prevent saturation of network or storage resources during the transfer.<br><br><b><b>--delete</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies whether to delete the original disk volume after a successful move. Defaults to <b>true</b> (1). Use with caution.<br><br><b><b>--discard</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables discard (TRIM) support on the target volume. Defaults to <b>true</b> (1) if the target storage supports and has discard enabled.<br><br><b><b>--format</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target disk image format. Valid values are <b>raw</b> and <b>qcow2</b>. If not specified, the format is often derived from the target storage type or attempts to retain the original.<br><br><b><b>--sparse</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates the new volume as a sparse volume if the target format and storage support it. Defaults to <b>false</b> (0).<br><br><b><b>--target-disk</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a new disk ID for the target disk (e.g., changing <b>scsi0</b> to <b>scsi1</b>). If not specified, the original disk ID is reused.<br><br><b><b>--target-volume</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows specifying a specific volume ID on the target storage. This option is primarily for internal use cases.<br><br>


title: DESCRIPTION
content:
<i>qm move_disk</i> is a subcommand of the Proxmox VE <i>qm</i> utility. It allows an administrator to move a virtual machine's disk image from its current storage location to a different storage backend configured within Proxmox VE. This operation typically requires the virtual machine to be <b>stopped</b> to ensure data integrity and avoid corruption. It is widely used for various administrative tasks such as rebalancing storage usage across different storage types (e.g., local storage to shared storage like Ceph or NFS), changing disk image formats (e.g., raw to qcow2), or preparing a VM's disk for migration to another host. The command handles the data transfer and automatically updates the VM's configuration to reflect the new disk location and parameters, simplifying complex storage management tasks.


title: CAVEATS
content:
<i>The virtual machine must generally be <b>stopped</b> before attempting to move a disk with qm move_disk to prevent data corruption and ensure a consistent state. Live disk migration is not supported by this specific command.</i><br><br><i>Ensure that the <i>target-storage</i> has sufficient free space to accommodate the disk, especially if converting from a sparse format to a thick-provisioned one.</i><br><br><i>The <b>--delete</b> option defaults to <b>true</b>. Always double-check your command to avoid accidental data loss of the original disk.</i><br><br><i>The command only supports converting between <b>raw</b> and <b>qcow2</b> formats explicitly. Other format changes are handled implicitly by the storage backend (e.g., LVM volumes).</i>


title: AUTOMATIC CONFIGURATION UPDATE
content:
Upon successful completion of the disk move, <i>qm move_disk</i> automatically updates the virtual machine's configuration file to reflect the new disk location and parameters on the target storage. This ensures the VM can start correctly with its disk in the new location.


title: STORAGE BACKEND COMPATIBILITY
content:
The command intelligently handles conversions and transfers between different types of Proxmox storage backends. For instance, you can move a disk from a local LVM storage to a network-attached NFS share, or from a local ZFS pool to a distributed Ceph RBD volume, with the utility managing the underlying complexities.


title: HISTORY
content:
<i>qm move_disk</i> is a fundamental feature within the Proxmox VE ecosystem, integrated into the <i>qm</i> utility since early versions. Its development has closely tracked the evolution of Proxmox's support for diverse storage backends (such as ZFS, LVM, Ceph, NFS, and iSCSI), providing administrators with flexible tools to manage and optimize VM storage. It remains a crucial command for rebalancing, consolidating, and preparing VM disks for various operational needs within a Proxmox cluster.


title: SYNOPSIS
content:
<b>qm-mtunnel</b> <b>--vmid</b> <i>&lt;VMID&gt;</i> <b>--type</b> <i>&lt;vnc|spice&gt;</i> [OPTIONS]


title: PARAMETERS
content:
<b><b>--vmid</b> <i>&lt;VMID&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the unique virtual machine ID for which the console tunnel should be established.<br><br><b><b>--type</b> <i>&lt;vnc|spice&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the type of graphical console protocol to tunnel, either <i>vnc</i> or <i>spice</i>.<br><br><b><b>--listen-fd</b> <i>&lt;FD&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Instructs the tunnel to listen on a pre-opened file descriptor instead of a specific port. This is often used for inter-process communication.<br><br><b><b>--listen-port</b> <i>&lt;PORT&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Specifies the TCP port number that the <b>qm-mtunnel</b> daemon will listen on for incoming tunnel connections. If not specified, a dynamic port is typically assigned by the calling process (e.g., `pveproxy`).<br><br><b><b>--ssl-cert</b> <i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Provides the file path to the SSL certificate for securing the WebSocket tunnel with TLS/SSL. Usually points to Proxmox's default SSL certificate.<br><br><b><b>--ssl-key</b> <i>&lt;FILE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Provides the file path to the SSL private key associated with the certificate, used for TLS/SSL encryption of the WebSocket tunnel.<br><br><b><b>--timeout</b> <i>&lt;SECONDS&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Sets the timeout for the WebSocket connection in seconds. The default value is 60 seconds.<br><br><b><b>--host</b> <i>&lt;IP&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Specifies the local IP address on which `qm-mtunnel` should bind its listening socket. By default, it listens on all available network interfaces (0.0.0.0).<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. Enables verbose debug logging output, which can be useful for troubleshooting connection issues.<br><br>


title: DESCRIPTION
content:
The <b>qm-mtunnel</b> command, also known as `pve-qemu-server-mtunnel`, is an internal utility within Proxmox Virtual Environment (PVE) designed to establish secure WebSocket tunnels for accessing virtual machine graphical consoles (VNC and SPICE). It acts as an intermediary, proxying connections from a client (e.g., a web browser using the PVE web interface or the `qm console` command) to the actual VNC or SPICE server running on the virtual machine. This mechanism allows users to access VM consoles even when the client is behind a firewall or NAT, or when direct access to the VM's VNC/SPICE port is not feasible or desired. It typically handles SSL/TLS encryption for the tunnel, ensuring secure data transmission. While it's a standalone executable, it is primarily invoked and managed by Proxmox's `pveproxy` service and `qemu-server` components rather than directly by users.


title: CAVEATS
content:
<b>qm-mtunnel</b> is an internal Proxmox VE component and is generally not intended for direct manual execution by users. Its proper functioning relies on the Proxmox environment and its associated services (like `pveproxy`). Improper direct usage can lead to security vulnerabilities or service disruption. It's designed to be invoked programmatically by the Proxmox web interface or the `qm console` command, which handle the necessary parameters and security contexts automatically.


title: ROLE IN PROXMOX WEB INTERFACE
content:
When you open a console to a VM from the Proxmox web interface, `pveproxy` (the Proxmox API daemon) initiates a call to `qm-mtunnel`. `qm-mtunnel` then creates a WebSocket server, often on a dynamically assigned port, and acts as a secure proxy between your browser's console client and the VM's VNC or SPICE server. This provides a single, secure entry point for console access, simplifying network configuration for users.


title: WEBSOCKET TUNNELING
content:
<b>qm-mtunnel</b> primarily utilizes WebSocket technology to create the tunnel. This allows for persistent, full-duplex communication over a single TCP connection, making it efficient for transmitting console data. When combined with SSL/TLS, it provides an encrypted and secure channel for sensitive console interactions, traversing network proxies and firewalls more easily than traditional VNC/SPICE direct connections.


title: HISTORY
content:
<b>qm-mtunnel</b> was developed as an integral part of Proxmox Virtual Environment to address the complexities of secure and seamless graphical console access for virtual machines. As Proxmox evolved to provide a robust web-based management interface, the need for a reliable tunneling solution became crucial, especially for environments where VMs are behind firewalls or in private networks. It has been a core component enabling the 'Console' feature in the Proxmox web UI, offering both VNC and SPICE connectivity securely over a WebSocket tunnel since its introduction, evolving with Proxmox VE releases to enhance stability and security.


title: PARAMETERS
content:
<b><i>IP_ADDRESS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The IP address (or hostname) where the NBD server to be stopped is listening. This must match the address used when the NBD server was started.<br><br><b><i>PORT</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The TCP port number where the NBD server to be stopped is listening. This must match the port used when the NBD server was started.<br><br>


title: DESCRIPTION
content:
The <b>qm-nbdstop</b> command is part of the Proxmox Virtual Environment (PVE) suite of tools, specifically designed to manage Network Block Device (NBD) servers. Its primary function is to cleanly shut down an NBD server instance that was previously started, typically by the <b>qm-nbdstart</b> command.<br><br>NBD allows a block device (like a virtual machine disk image) to be exported over a network, making it accessible as a local block device on a client machine. In Proxmox, this capability is crucial for various advanced operations such as live storage migration, performing online backups of running virtual machines, or mounting a VM's disk image for external manipulation without needing to power down the VM.<br><br>When <b>qm-nbdstart</b> exports a VM disk on a specific IP address and port, <b>qm-nbdstop</b> is then used to terminate that export, releasing the associated resources and ensuring data integrity. It's essential for maintaining a clean and controlled environment when leveraging NBD for VM disk access.


title: CAVEATS
content:
<ul><li>The <b>qm-nbdstop</b> command relies on the NBD server process being responsive and accessible at the specified IP and port.</li><li>It only stops the NBD server process; it does not unmount or detach the NBD device on any client systems that might be connected. Clients must unmount or detach their NBD devices independently.</li><li>If the NBD server process is unresponsive or has crashed, <b>qm-nbdstop</b> may fail, requiring manual intervention (e.g., using `kill` to terminate the process).</li><li>Proper permissions are required to terminate the NBD server process, typically root privileges.</li></ul>


title: HISTORY
content:
The `qm-nbdstart` and `qm-nbdstop` commands are integral parts of the Proxmox Virtual Environment (PVE) management toolset. Their development is closely tied to PVE's evolution, especially its focus on advanced storage management and live migration capabilities. These commands serve as high-level wrappers or direct invocations of underlying NBD utilities (like `qemu-nbd`), providing a user-friendly interface for Proxmox administrators. They were introduced to facilitate operations like online VM backups and seamless storage migrations, becoming a standard part of the PVE ecosystem since the introduction of robust NBD support within Proxmox VE.


title: PARAMETERS
content:
<b><i>(No options)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>qm-pending</b> command is typically executed without any command-line options or arguments. It provides its output based on the current state of the <b>Qmail</b> queue directories and does not accept flags to modify its behavior.<br><br>


title: DESCRIPTION
content:
<i>qm-pending</i> is a utility program provided with the <b>Qmail</b> Mail Transfer Agent (MTA). Its primary function is to report the current status of the <b>Qmail</b> message queue. Specifically, it counts and displays the number of messages that are currently awaiting delivery.<br><br>The output typically differentiates between messages destined for local delivery (i.e., to users on the same server) and those destined for remote delivery (i.e., to users on other servers via SMTP). This command is crucial for system administrators to quickly assess the load and health of their <b>Qmail</b> installation, identify potential bottlenecks, or confirm whether messages are being processed as expected. It provides a simple, direct snapshot of the queue's backlog, which can be useful for monitoring scripts or manual troubleshooting. Its simplicity and focus on a single task are characteristic of the <b>Qmail</b> suite's modular design.


title: CAVEATS
content:
<b>qm-pending</b> is part of the <b>Qmail</b> MTA and is not a standard Linux command found on systems without a <b>Qmail</b> installation. Its functionality is limited to reporting message counts; it does not provide detailed information about individual messages, nor does it allow for queue manipulation. Access to the <b>Qmail</b> queue directories is required for accurate counts, which often means running the command with appropriate permissions (e.g., as the <i>qmailr</i> user or root).


title: OUTPUT FORMAT
content:
The command typically outputs two numeric values. The first number represents the count of messages awaiting <i>local</i> delivery, and the second represents the count of messages awaiting <i>remote</i> delivery. For example, an output of "<code>10 5</code>" means 10 messages are pending for local delivery and 5 for remote delivery.<br><br>The exact formatting (e.g., space-separated, newlines) can vary slightly depending on the specific <b>Qmail</b> package or wrapper script used, but the meaning of the two numbers is consistent.


title: TYPICAL LOCATION
content:
On a standard <b>Qmail</b> installation, the <b>qm-pending</b> executable is usually located in the <code>/var/qmail/bin/</code> directory or a similar designated <b>Qmail</b> binary path. It is often a lightweight shell script that performs directory traversals and counts.


title: HISTORY
content:
The <b>Qmail</b> Mail Transfer Agent, including utilities like <b>qm-pending</b>, was developed by Daniel J. Bernstein (DJB) in the mid-1990s. It was designed with a strong emphasis on security, reliability, and performance, aiming to be a more robust alternative to existing MTAs at the time. <b>qm-pending</b> embodies <b>Qmail</b>'s philosophy of providing small, single-purpose tools that work together. It has remained a stable component of the <b>Qmail</b> ecosystem since its inception, reflecting the enduring design of the core MTA.


title: PARAMETERS
content:
<b><b>&lt;vmid&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The numeric ID of the virtual machine (VM) to reboot. This is a mandatory argument.<br><br><b><b>-force</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a hard reset if the clean, ACPI-based reboot fails to complete within the specified timeout. Use with caution as it can be abrupt and similar to pulling the power.<br><br><b><b>-timeout &lt;seconds&gt;</b>, <b>--timeout &lt;seconds&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of seconds to wait for the guest operating system to perform the graceful reboot. The default timeout is 60 seconds.<br><br><b><b>-skiplock</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows the command to proceed even if the virtual machine is currently locked. This option should be used carefully to avoid conflicts with ongoing operations.<br><br>


title: DESCRIPTION
content:
<I>qm-reboot</I> is a command-line utility provided by Proxmox Virtual Environment (PVE) for managing QEMU/KVM virtual machines. Its primary function is to initiate a soft, ACPI-based reboot of a running virtual machine. Unlike a hard reset or power cycle, <I>qm-reboot</I> sends an ACPI reboot signal to the guest operating system, allowing it to perform a graceful shutdown sequence before restarting. This method is preferred for data integrity and system stability within the guest. It's an essential tool for administrators to manage VM lifecycle events from the Proxmox host.<br><br>The command requires the VM ID (VMID) as an argument and can optionally specify a timeout for the reboot operation. It ensures a controlled restart, minimizing potential data corruption compared to an abrupt power cycle.


title: CAVEATS
content:
For optimal behavior, the QEMU Guest Agent (QGA) and ACPI must be functional and installed/enabled within the guest OS. If these are not properly configured, <I>qm-reboot</I> might only wait for the timeout before failing, or requiring the use of <B>-force</B> which then performs a hard reset.<br><br>Using <B>-force</B> immediately can bypass the graceful shutdown, making it similar to <I>qm reset</I> if the guest doesn't respond instantly. Always consider allowing the default timeout to pass first.


title: QEMU GUEST AGENT (QGA)
content:
For <I>qm-reboot</I> to function optimally and provide a truly graceful reboot, the QEMU Guest Agent (QGA) should be installed and running inside the virtual machine. QGA enables direct communication between the Proxmox host and the guest OS, facilitating clean shutdowns, reboots, and other operations like retrieving network information. Without QGA, the command relies solely on ACPI signals, which might not always be as reliable or immediate depending on the guest OS configuration.


title: ACPI SUPPORT
content:
The Advanced Configuration and Power Interface (ACPI) must be correctly recognized and handled by the guest operating system. <I>qm-reboot</I> primarily sends an ACPI reboot signal. If the guest OS does not properly respond to ACPI events (e.g., due to missing drivers or misconfiguration), the graceful reboot might not occur as expected, potentially leading to a timeout and requiring a forced reset.


title: HISTORY
content:
<I>qm-reboot</I> is an integral part of the Proxmox Virtual Environment (PVE), a leading open-source virtualization platform first released in 2007. This command, along with other <I>qm</I> utilities, has been a core component of Proxmox's VM management capabilities since its early versions. It evolved to provide administrators with a reliable and safe method for initiating controlled VM restarts directly from the Proxmox host, essential for maintaining stable production environments and leveraging the underlying QEMU/KVM virtualization technologies effectively.


title: PARAMETERS
content:
<b>--storage <i>&lt;id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rescan a specific storage identified by its unique <i>&lt;id&gt;</i>.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rescan all currently configured storage backends within the Proxmox VE environment.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a simulated run, showing what actions would be taken without actually making any modifications to the storage or its metadata.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase the verbosity of the output, providing more detailed information about the scanning process.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the rescan operation, potentially overriding certain internal locks or busy states. Use with extreme caution as it can interfere with ongoing operations if not understood properly.<br><br><b>--skip-locked</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>--all</b>, this option instructs <b>qm-rescan</b> to skip any storages that are currently locked. This is the default behavior when <b>--all</b> is specified.<br><br><b>--fix-errors</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to automatically fix certain types of detected errors during the rescan process, such as missing physical devices for LVM-based storage groups.<br><br>


title: DESCRIPTION
content:
<b>qm-rescan</b> is a specialized internal utility within the Proxmox VE (Virtual Environment) ecosystem. Its primary function is to refresh and update the Proxmox cluster's view of configured storage backends. This involves scanning storage types such as LVM, ZFS, directory, iSCSI, and NFS to discover new volumes, verify the integrity of existing ones, and synchronize metadata.<br><br>It is particularly useful when manual changes have been made to the underlying storage outside of the Proxmox web interface or API, ensuring that Proxmox VE accurately recognizes and manages all available storage resources for virtual machines and containers. While it can be executed directly by an administrator, it is also frequently invoked internally by other Proxmox tools or system services to maintain storage consistency.


title: CAVEATS
content:
Running <b>qm-rescan</b>, especially with the <b>--all</b> option, can be I/O intensive and may take a significant amount of time on systems with large or numerous storage configurations. Using the <b>--force</b> option should be done with extreme care, as it can potentially disrupt ongoing storage operations or data consistency if not used in appropriate scenarios.


title: INTEGRATION WITH PROXMOX VE
content:
Although <b>qm-rescan</b> can be executed directly from the command line, it is often invoked internally by other Proxmox services or by administrator actions through the Proxmox web interface. For instance, creating or modifying storage in the GUI or via <b>pvesm</b> commands can trigger an internal rescan. Its primary role is to ensure the cluster's distributed storage view remains synchronized with the actual state of the underlying storage resources.


title: HISTORY
content:
<b>qm-rescan</b> is an integral part of the Proxmox VE storage management framework, having been a core utility since the early versions of Proxmox VE. Its development has evolved alongside the expanding support for various storage technologies, ensuring consistent and reliable storage management within the Proxmox environment.


title: PARAMETERS
content:
<b>vmid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numeric ID of the virtual machine (VM) to reset.<br><br>


title: DESCRIPTION
content:
<b><code>qm reset</code></b> is a Proxmox VE command used to forcefully restart a QEMU/KVM virtual machine. It acts like a hard power cycle, similar to pressing the reset button on a physical computer. This command is typically employed when a virtual machine becomes unresponsive, is frozen, or cannot be gracefully shut down using <b><code>qm shutdown</code></b> or <b><code>qm stop</code></b>. It bypasses the guest operating system's shutdown process, immediately powering off the VM and then restarting it. While effective for unresponsive VMs, it carries a risk of data corruption if the guest OS was writing data at the time of the reset. Therefore, it should be used as a last resort when other graceful methods fail.


title: CAVEATS
content:
Using <b><code>qm reset</code></b> can lead to data loss or file system corruption within the guest operating system, especially if the VM was actively writing data when reset. It should be used as a last resort when graceful shutdown or stop commands fail. Always ensure important data is backed up before resorting to a forced reset.


title: DIFFERENCE FROM SHUTDOWN/STOP
content:
Unlike <b><code>qm shutdown &lt;vmid&gt;</code></b>, which attempts a graceful ACPI shutdown of the guest OS, or <b><code>qm stop &lt;vmid&gt;</code></b>, which sends a power-off signal but waits a short period, <b><code>qm reset &lt;vmid&gt;</code></b> performs an immediate and forceful power cycle. This means it does not wait for the guest OS to clean up processes or flush data, making it quicker but riskier for data integrity.


title: HISTORY
content:
The <b><code>qm reset</code></b> command is an integral part of the Proxmox VE (Virtual Environment) ecosystem, a comprehensive open-source platform for enterprise virtualization. It is provided by the <code>qemu-server</code> package, which manages QEMU/KVM virtual machines within Proxmox. Its development and usage are intrinsically linked to the evolution of Proxmox VE, offering administrators a crucial tool for managing unresponsive VMs since early versions of the platform.


title: PARAMETERS
content:
<b>&lt;vmid&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique ID of the virtual machine or container.<br><br><b>&lt;disk&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The identifier of the disk to resize (e.g., 'scsi0', 'ide0', 'virtio0', or 'rootfs' for containers).<br><br><b>&lt;size&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target size or the amount to add/subtract. Can be an absolute size (e.g., '100G') or a delta (e.g., '+10G', '-5G'). Supported units are K, M, G, T.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform a dry run; do not actually resize the disk, but show what would happen.<br><br><b>--sparse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Try to make the disk image sparse after shrinking. Only applicable for file-based storages.<br><br><b>--shrink</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b><I>Mandatory option for shrinking operations</I></b> to explicitly acknowledge the risk of data loss. This prevents accidental shrinking.<br><br>


title: DESCRIPTION
content:
<br>The <b>qm-resize</b> command is a specialized utility within the Proxmox Virtual Environment (PVE) designed to modify the size of virtual disk images attached to KVM virtual machines (VMs) and LXC containers (CTs). It allows administrators to either extend the capacity of a virtual disk, providing more storage space to the guest operating system, or cautiously shrink it to reclaim unused space on the host storage.<br><br>Crucially, <b>qm-resize</b> operates at the storage backend level, meaning it interacts directly with the underlying storage (e.g., LVM, ZFS, Ceph RBD, directory-backed files). It does not automatically resize the filesystem <i>inside</i> the guest. For extending, users typically resize the guest's filesystem (e.g., using <b>resize2fs</b> or <b>xfs_growfs</b>) after increasing the disk size with <b>qm-resize</b>. For shrinking, <i>it is imperative to shrink the guest's filesystem first</i> to prevent data loss, and the guest must be powered off for shrinking operations.


title: CAVEATS
content:
<i><br><b>Data Loss Warning for Shrinking:</b></i> When shrinking a disk, it is absolutely critical to first reduce the size of the filesystem <I>inside</I> the guest operating system. Failing to do so before running <b>qm-resize --shrink</b> will result in immediate and irreversible data loss. This command only modifies the underlying block device size, not the filesystem within.<br><br><b>Guest State:</b> Shrinking operations generally require the VM or container to be powered off. While some online extension capabilities exist for certain storage types, it's often safer and recommended to power off the guest for any resizing operation, especially when dealing with critical data.<br><br><b>Filesystem Resizing:</b> After extending a disk with <b>qm-resize</b>, you must manually extend the filesystem inside the guest to utilize the newly available space (e.g., using <b>resize2fs</b>, <b>xfs_growfs</b>, or other filesystem-specific tools).


title: USAGE CONSIDERATIONS
content:
While <b>qm-resize</b> directly manipulates the virtual disk size, for Proxmox users, it's often more common to use the higher-level commands like <b>qm set &lt;vmid&gt; --&lt;disk_id&gt; &lt;size&gt;</b> or <b>pct set &lt;vmid&gt; --rootfs &lt;size&gt;</b>. These commands internally call <b>qm-resize</b>, providing a more integrated and user-friendly experience, especially when dealing with configuration updates through the Proxmox web interface or CLI.


title: COMMON WORKFLOW
content:
<b><I>Extending a Disk:</I></b><br>1. Power off the VM/CT (recommended, sometimes optional).<br>2. Use <b>qm-resize</b> (or <b>qm set</b>/<b>pct set</b>) to increase the virtual disk size.<br>3. Power on the VM/CT.<br>4. Inside the guest, extend the partition (if applicable) and then the filesystem (e.g., <b>resize2fs /dev/vda1</b> or <b>lvextend</b> then <b>xfs_growfs</b>).<br><br><b><I>Shrinking a Disk:</I></b><br>1. Power off the VM/CT.<br>2. Inside the guest, shrink the filesystem first (e.g., <b>resize2fs -M /dev/vda1</b>).<br>3. Inside the guest, shrink the partition (if applicable).<br>4. Use <b>qm-resize --shrink</b> (or <b>qm set</b>/<b>pct set</b>) to reduce the virtual disk size on the host.<br>5. Power on the VM/CT.


title: HISTORY
content:
<b>qm-resize</b> is an integral part of the Proxmox Virtual Environment (PVE) suite of utilities, developed alongside the platform itself to provide robust virtual machine and container management capabilities. Its evolution has mirrored the growing sophistication of PVE's storage management, supporting various backend technologies like LVM, ZFS, Ceph, and standard file-based storages. It serves as a backend helper script, primarily invoked by higher-level <b>qm</b> or <b>pct</b> commands for disk modification, emphasizing Proxmox's design philosophy of providing comprehensive, integrated virtualization tools.


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique integer identifier for the virtual machine to be resumed.<br><br>


title: DESCRIPTION
content:
The <b>qm-resume</b> command is an integral part of the Proxmox VE (Virtual Environment) suite, specifically designed for managing KVM/QEMU virtual machines.<br><br>It is used to restore a virtual machine from a suspended state back to its running operation. This differs from <b>qm-start</b>, which powers on a VM that was fully shut down or stopped. A suspended VM preserves its entire RAM content, CPU state, and device states, allowing for a quick return to its previous operational point.<br><br>Typically, a VM can be suspended either to RAM (a quicker but volatile state) or to disk (hibernation, slower but persistent across host reboots). <b>qm-resume</b> intelligently detects the saved state and reloads it, making it crucial for scenarios like host maintenance, migration, or simply pausing a VM's execution without fully shutting it down. Proper usage ensures the VM's workload continues seamlessly from where it left off.


title: CAVEATS
content:
The VM must have been previously suspended using <b>qm suspend</b> for <b>qm-resume</b> to work. If the VM was stopped or powered off, use <b>qm-start</b> instead.<br><br>Resuming a VM can consume significant host memory if the VM was suspended to RAM, or disk I/O if hibernated.<br><br>Hardware changes on the host system (e.g., CPU, memory configuration) between suspension and resume might cause issues or instability within the guest OS.<br><br>Requires appropriate permissions (root or sudo) to execute Proxmox VE management commands.


title: PROXMOX VE CONTEXT
content:
The <b>qm-resume</b> command is not a standalone Linux utility found in standard distributions. It is part of the <i>pve-qemu-kvm</i> package within the Proxmox VE environment. It acts as a high-level wrapper that orchestrates the underlying QEMU/KVM commands and manages Proxmox's internal configuration databases.


title: PERMISSIONS
content:
To execute <b>qm-resume</b>, the user must have administrative privileges on the Proxmox VE host, typically by running the command as <i>root</i> or using <i>sudo</i>.


title: HISTORY
content:
<b>qm-resume</b> is a core component of the Proxmox VE project, a specialized Linux distribution for virtualization. As Proxmox VE matured since its inception around 2007, the <b>qm</b> utility and its subcommands, including <b>qm-resume</b>, have been continuously developed and refined to provide robust and intuitive management of KVM/QEMU virtual machines. Its existence is tied directly to the evolution and widespread adoption of Proxmox VE as an open-source virtualization platform.


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numerical ID of the virtual machine to be rolled back. This ID identifies the specific VM within the Proxmox VE environment.<br><br><b><i>&lt;snapname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the existing snapshot to which the virtual machine should be reverted. This snapshot must have been created previously using <b>qm snapshot</b>.<br><br>


title: DESCRIPTION
content:
The <b>qm-rollback</b> command in Proxmox VE is used to revert a QEMU/KVM virtual machine to a previously created snapshot state. This command is a critical part of Proxmox's VM management toolkit, allowing administrators to undo changes made since a specific point in time. When executed, <b>qm-rollback</b> restores the VM's disk images and configuration to precisely how they were when the designated snapshot was taken. <br><br> Before initiating a rollback, the target virtual machine <i>must be powered off</i>. It is crucial to understand that this is a <i>destructive operation</i>: all data, configurations, and changes made to the VM *after* the snapshot was created will be permanently lost and cannot be recovered. Therefore, it should be used with extreme caution and only after verifying the desired state. <br><br> This functionality is invaluable for quick recovery from erroneous system updates, failed software installations, or undesirable configuration changes during testing environments. While powerful for immediate recovery, <b>qm-rollback</b> is not a substitute for a comprehensive backup strategy, as snapshots are typically stored on the same storage as the VM itself.


title: CAVEATS
content:
<ul><li>The virtual machine <i>must be stopped (powered off)</i> before a rollback operation can be performed.</li><li>A rollback is a <i>destructive operation</i>; all changes, data, and configurations made to the VM after the selected snapshot was taken will be permanently lost and are unrecoverable.</li><li>The rollback operation affects all disk images associated with the VM and included in the snapshot.</li><li>The VM's configuration (e.g., RAM, CPU settings, network interfaces) will also be reverted to the state it was in at the time the snapshot was created.</li><li>Snapshots are typically stored on the same storage as the VM's disks, so they do not protect against storage failures. They are not a substitute for proper backups.</li></ul>


title: VM STATE REQUIREMENT
content:
For <b>qm-rollback</b> to execute successfully, the target virtual machine <i>must be in a stopped or powered-off state</i>. Attempting to roll back a running VM will result in an error.


title: IRREVERSIBLE DATA LOSS
content:
Users are strongly advised to understand that rolling back a VM will <i>permanently delete</i> all data and configuration changes made since the chosen snapshot. There is no undo functionality for this operation.


title: HISTORY
content:
The <b>qm-rollback</b> command is an integral part of the Proxmox Virtual Environment (PVE) management toolset, specifically designed for QEMU/KVM virtual machines. Its functionality has been available since early versions of Proxmox VE, evolving alongside the platform's robust snapshot capabilities. It leverages QEMU's underlying snapshot mechanisms, abstracting them into an easy-to-use command-line interface for administrators. Its core purpose – to quickly revert a VM to a known good state – has remained consistent, making it a staple for development, testing, and recovery scenarios within Proxmox environments.


title: PARAMETERS
content:
<b><b>&lt;vmid&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The unique numeric identifier of the target virtual machine (e.g., 100, 101).</i><br><br><b><b>&lt;key&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>One or more key names to send sequentially to the VM. Keys can be simple characters (e.g., 'a', '1', '!'), common keys (e.g., 'enter', 'tab', 'esc', 'delete', 'backspace', 'up', 'down', 'left', 'right'), function keys (f1-f12), or combinations using hyphens (e.g., 'ctrl-alt-del', 'shift-tab', 'left-super'). Common modifier keys include 'ctrl', 'alt', 'shift', 'super'.</i><br><br>


title: DESCRIPTION
content:
The <b>qm-sendkey</b> command is a powerful utility within the Proxmox Virtual Environment (PVE) designed to send emulated keyboard input directly to a running QEMU/KVM virtual machine. This capability is crucial for interacting with a VM's console when standard network access (like SSH or RDP) is unavailable or when the guest operating system is not fully booted or is unresponsive.<br><br>It enables administrators to perform essential actions such as triggering a hard reboot (e.g., by sending <i>ctrl-alt-del</i>), navigating BIOS/UEFI settings during boot, interacting with bootloaders like GRUB, or providing simple character inputs during an OS installation or recovery process. The command communicates directly with the underlying QEMU monitor of the specified VM, bypassing the guest OS's network stack or internal processes. This makes it effective even if the guest OS is hung or has no network configuration.<br><br>It supports a wide range of keys, including individual alphanumeric characters, function keys (<i>F1-F12</i>), arrow keys, special keys (<i>Esc</i>, <i>Tab</i>, <i>Enter</i>, <i>Delete</i>, <i>Backspace</i>), and combinations involving modifier keys (<i>Ctrl</i>, <i>Alt</i>, <i>Shift</i>, <i>Super</i>). Combinations are specified with hyphens, such as <i>ctrl-alt-del</i> or <i>shift-tab</i>.


title: CAVEATS
content:
<i>Requires the virtual machine to be in a 'running' state for key presses to be effective.<br>This command operates at the QEMU monitor level and does not require the QEMU Guest Agent to be installed or running within the VM, making it suitable for unbootable or unresponsive guests.<br>Rapid successive key presses might not be reliably processed by a sluggish guest OS; consider adding a small delay if scripting complex key sequences.<br>Executing this command requires administrative (root or sudo) privileges on the Proxmox host.</i>


title: TYPICAL USAGE SCENARIOS
content:
<i><b>Emergency Reboot:</b> Sending <i>ctrl-alt-del</i> to initiate a controlled or forced reboot on a frozen or unresponsive guest operating system, similar to pressing those keys on a physical machine.<br><b>BIOS/UEFI Access:</b> Pressing <i>del</i>, <i>f2</i>, <i>f10</i>, or other vendor-specific keys during the VM's very early boot sequence to enter BIOS/UEFI settings for configuration changes.<br><b>Bootloader Interaction:</b> Navigating menus in bootloaders like GRUB, or selecting different boot options in Windows Boot Manager before the operating system fully loads.<br><b>Initial OS Setup:</b> Providing simple keyboard inputs during initial text-based OS installation steps, such as selecting a language or accepting a license agreement, when direct console access is preferred or necessary.</i>


title: HISTORY
content:
<i>The <b>qm-sendkey</b> functionality is an integral part of the Proxmox VE's command-line interface, leveraging the underlying QEMU monitor's capability to inject key events directly into virtual machines. It has been available since early versions of Proxmox VE, reflecting its fundamental role in bare-metal VM management and troubleshooting. Its design is closely tied to the evolution of QEMU/KVM itself, providing a robust, low-level method of interaction with virtual machines that complements higher-level management tools.</i>


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numeric identifier (ID) of the virtual machine or container whose launch command you wish to display. This is a mandatory argument.<br><br><b><b>--pretty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats the output command with line breaks and indentation, making it more readable and easier to analyze. Without this option, the command is printed as a single, long line.<br><br><b><b>--with-defaults</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes all default parameters that Proxmox implicitly adds to the command line, even if they are not explicitly configured for the VM/CT. This provides a complete picture of all QEMU/LXC arguments.<br><br><b><b>--with-vmid</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prepends the VMID to the output command line, which can be useful when processing the output for multiple VMs programmatically.<br><br>


title: DESCRIPTION
content:
The <b>qm-showcmd</b> utility is a diagnostic tool within the Proxmox Virtual Environment (PVE) ecosystem. Its primary function is to reveal the exact command-line arguments that Proxmox VE uses internally to launch a specified virtual machine (VM) or container (CT) using QEMU/KVM or LXC. <br><br>When Proxmox starts a VM, it generates a complex <b>qemu-system-x86_64</b> command with numerous parameters defining hardware, network, storage, and other configurations. Similarly, for containers, it generates the corresponding LXC command. <b>qm-showcmd</b> allows administrators and users to inspect this command. <br><br>This command is invaluable for debugging, understanding how Proxmox translates its configuration files into QEMU/LXC parameters, or for replicating a VM's environment outside of Proxmox for advanced troubleshooting or custom setups. It does not execute the command; it merely displays it.


title: CAVEATS
content:
The output of <b>qm-showcmd</b> is for informational and diagnostic purposes only. It displays the command that *would be* executed, but does not actually run or validate it. Attempting to run the displayed command manually outside of Proxmox may require elevated privileges and a carefully prepared environment. The command line can be extremely long and complex, especially for VMs with many devices or custom configurations.


title: OUTPUT STRUCTURE
content:
The typical output of <b>qm-showcmd</b> for a VM will be a full <b>qemu-system-x86_64</b> command followed by numerous <b>-device</b>, <b>-nic</b>, <b>-drive</b>, <b>-cpu</b>, and other options. For a container, it will show an <b>lxc-start</b> or similar LXC command with its relevant parameters. Using the <b>--pretty</b> option significantly improves readability by breaking down the command into multiple lines, with each major argument on its own line.


title: HISTORY
content:
<b>qm-showcmd</b> has been a part of the Proxmox Virtual Environment (PVE) suite since its relatively early versions. It was introduced to address the need for administrators to understand the complex QEMU command lines generated by PVE's abstracted configuration. As Proxmox VE evolved to manage increasingly sophisticated virtual machine and container setups, the complexity of the underlying QEMU/LXC commands grew. <b>qm-showcmd</b> became an essential debugging and transparency tool, helping users diagnose issues related to specific QEMU parameters, verify configurations, and gain deeper insight into PVE's internal workings. Its continuous presence underscores its utility for Proxmox administrators and developers.


title: PARAMETERS
content:
<b><i><b>&lt;vmid&gt;</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numeric ID of the virtual machine or container to be shut down. This is a mandatory argument.<br><br><b><i><b>--timeout &lt;integer&gt;</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum time in seconds to wait for the guest operating system to perform its graceful shutdown. If the guest does not shut down within this period, a forceful stop will be executed. The default value is typically 60 or 120 seconds, depending on the Proxmox VE version.<br><br><b><i><b>--keep-active &lt;boolean&gt;</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When set to <i><b>1</b></i> or <i><b>true</b></i>, this option prevents the VM/CT from being forcibly stopped even if the ACPI shutdown fails or times out. The guest will remain active, which can be useful for debugging unresponsive systems without immediately killing them. Defaults to <i><b>0</b></i> or <i><b>false</b></i>.<br><br>


title: DESCRIPTION
content:
<i><b>qm-shutdown</b></i> is a crucial command within the Proxmox Virtual Environment (PVE) for managing virtual machines (VMs) and containers (CTs).<br>Its primary function is to initiate a controlled and graceful shutdown process for a running guest operating system. Unlike a forceful stop, <i><b>qm-shutdown</b></i> first attempts to send an ACPI (Advanced Configuration and Power Interface) shutdown signal to the guest.<br>This allows the guest OS to perform its standard shutdown routines, such as flushing disk caches, closing applications, and safely unmounting filesystems, thereby minimizing the risk of data corruption.<br>If the guest does not respond to the ACPI signal or fails to shut down within a specified timeout period, <i><b>qm-shutdown</b></i> will then proceed to forcibly stop the VM/CT.<br>This command is highly recommended over immediate forceful stops (like <i><b>qm stop</b></i>) for maintaining the integrity and consistency of data within your virtualized environments.


title: CAVEATS
content:
The effectiveness of <i><b>qm-shutdown</b></i> relies on the guest operating system's ability to respond to ACPI signals. If the guest OS is frozen, lacks ACPI support, or if the QEMU Guest Agent is not properly installed and running (especially important for Windows VMs), the graceful shutdown may fail, leading to a timeout and subsequent forceful termination.<br>It is not an instantaneous kill command; it involves a waiting period.


title: GRACEFUL VS. FORCEFUL SHUTDOWN
content:
It's crucial to understand the distinction between <i><b>qm-shutdown</b></i> and <i><b>qm stop</b></i>. <i><b>qm-shutdown</b></i> prioritizes data integrity by giving the guest OS time to clean up. <i><b>qm stop</b></i>, in contrast, immediately kills the VM/CT process, which can lead to data corruption or loss if the guest OS was writing data or had open files. Always prefer <i><b>qm-shutdown</b></i> unless an immediate, ungraceful halt is absolutely necessary.


title: ROLE OF QEMU GUEST AGENT
content:
For optimal performance and reliable graceful shutdowns, especially with Windows guests, it is highly recommended to install and run the QEMU Guest Agent within the virtual machine. The guest agent facilitates communication between the Proxmox host and the guest OS, enabling features like proper ACPI shutdown handling, accurate IP address reporting, and file system freezing for backups.


title: HISTORY
content:
<i><b>qm-shutdown</b></i> has been an integral part of Proxmox VE since its early versions, evolving alongside the platform to offer robust VM and container lifecycle management. Its design reflects a balance between system stability and data integrity, with options like <i><b>--timeout</b></i> and <i><b>--keep-active</b></i> being introduced to provide more granular control over the shutdown process.


title: SEE ALSO
content:
<i><b>qm(1)</b></i>, <i><b>qm start(1)</b></i>, <i><b>qm stop(1)</b></i>, <i><b>qm reset(1)</b></i>, <i><b>qm status(1)</b></i>, <i><b>pct(1)</b></i>


title: SYNOPSIS
content:
<b>qm snapshot</b> <i>&lt;vmid&gt;</i> <b>create</b> <i>&lt;snapname&gt;</i> [OPTIONS]<br>
<b>qm snapshot</b> <i>&lt;vmid&gt;</i> <b>delete</b> <i>&lt;snapname&gt;</i><br>
<b>qm snapshot</b> <i>&lt;vmid&gt;</i> <b>revert</b> <i>&lt;snapname&gt;</i><br>
<b>qm snapshot</b> <i>&lt;vmid&gt;</i> <b>list</b>


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numeric identifier of the virtual machine to manage.<br><br><b><i>&lt;snapname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A unique alphanumeric name for the snapshot being created, deleted, or reverted to.<br><br><b><b>--description</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides a descriptive text for the snapshot (used with <b>create</b>).<br><br><b><b>--vmstate</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set to 1 (true) to include the VM's memory and running state in the snapshot (live snapshot). If 0 (false) or omitted, only the disk state is saved. Defaults to 0 (used with <b>create</b>).<br><br><b><b>--force</b> <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set to 1 (true) to force the operation, for example, to delete a snapshot that is a parent of other snapshots (used with <b>delete</b>).<br><br><b><b>--storage</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the storage to save the VM's memory state when creating a live snapshot (with <b>--vmstate 1</b>).<br><br>


title: DESCRIPTION
content:
The term "qm-snapshot" typically refers to the functionality accessed via the <b>qm snapshot</b> subcommand within Proxmox VE (PVE). It is not a standalone command but an integral part of the <b>qm</b> command-line utility for managing KVM virtual machines. This powerful tool allows Proxmox administrators to create, delete, revert to, and list snapshots of their VMs. Snapshots capture the disk state and optionally the memory and running state of a VM at a specific point in time. They are crucial for creating restore points, testing system changes, and enabling efficient backup and recovery strategies within a Proxmox VE environment. The underlying snapshot mechanism leverages storage technologies such as ZFS, LVM thin provisioning, or QCOW2 files.


title: CAVEATS
content:
Snapshots can consume significant disk space, especially if many are chained or if VMs have high disk I/O. Reverting a snapshot discards all changes made to the VM's disk and optionally memory state since the snapshot was taken. Live snapshots (`--vmstate 1`) can be I/O intensive during creation and might briefly impact VM performance. Not all storage types fully support snapshots (e.g., direct-attached storage without LVM-thin or ZFS layers). Deleting snapshots, particularly parent snapshots, might take time as data is merged or blocks are freed. Frequent snapshot creation and deletion, or long snapshot chains, can sometimes lead to performance degradation or complex management.


title: SNAPSHOT TYPES
content:
<b>Disk-only Snapshots:</b> These snapshots capture only the VM's disk state. For data integrity, the VM should ideally be stopped or paused during creation. If created on a running VM without <b>--vmstate</b>, it briefly pauses the VM to ensure a consistent disk state.<br>
<b>Live Snapshots (with VM state):</b> Created using the <b>--vmstate 1</b> option, these snapshots capture both the VM's disk state and its current memory/running state. This allows for a VM to be restored to its exact running condition without downtime during the snapshot process. They require additional storage space to save the memory dump.


title: SNAPSHOT CHAINS AND DELETION
content:
Snapshots form a chain, where each new snapshot references the state of its parent. When reverting to a parent snapshot, any subsequent (newer) snapshots in that branch become unusable or require forced deletion. Deleting a snapshot in the middle of a chain typically involves merging its unique data into the next snapshot in the chain, which can be a time-consuming I/O operation depending on the amount of changed data.


title: HISTORY
content:
The <b>qm snapshot</b> subcommand has been an essential feature of Proxmox VE since its early versions, providing a robust mechanism for VM state management. Its development has closely tracked the evolution of storage technologies supported by Proxmox, including LVM-thin, ZFS, and QCOW2. The command's design aligns with the broader <b>qm</b> utility's philosophy of offering comprehensive command-line control over virtual machines, ensuring consistency with other VM operations like starting, stopping, and migrating. Its capabilities have expanded to support both disk-only and live (memory-included) snapshots to meet diverse operational needs.


title: SYNOPSIS
content:
<b>qm start &lt;vmid&gt; [OPTIONS]</b><br><br><b>Arguments:</b><br>&lt;vmid&gt; &nbsp; &nbsp; &nbsp; The unique numeric ID of the virtual machine or container to start.


title: PARAMETERS
content:
<b>--timeout <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maximum startup time in seconds. If the VM/CT does not start within this period, the command exits with an error. Defaults to 300 seconds (5 minutes).<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ignores and clears existing locks (e.g., if a previous task failed or was interrupted). Use with caution, as it can lead to inconsistent states.<br><br><b>--skiplock</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips checking for locks, allowing the command to proceed even if another operation might be in progress. Less aggressive than <i>--force</i>.<br><br><b>--stateless</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the VM in stateless mode. All changes made during the session are discarded on shutdown, reverting to the last saved state or a snapshot. This is primarily for QEMU/KVM VMs.<br><br><b>--digitalsign <signature></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a digital signature for secure boot. Rarely used in typical scenarios.<br><br>


title: DESCRIPTION
content:
The <i>qm-start</i> command is a crucial utility within the Proxmox Virtual Environment (PVE) suite, designed to initiate the operation of virtual machines (VMs) and containers (CTs). It leverages QEMU/KVM for VMs and LXC for containers, providing a unified command-line interface for managing their lifecycle. When invoked, <i>qm-start</i> checks the specified VM or CT ID, allocates necessary resources based on its configuration (CPU, memory, storage, network), and then powers it on. This command is fundamental for bringing virtualized workloads online after creation, after a graceful shutdown, or following a power outage. It ensures that the guest operating system within the VM or CT begins its boot sequence, making the virtualized environment accessible and operational. The command typically returns successfully once the boot process has begun, not necessarily when the guest OS is fully loaded.


title: CAVEATS
content:
Starting a VM or CT requires sufficient host resources (CPU, RAM, storage). If resources are over-provisioned or unavailable, the command may fail or the VM/CT may not boot properly. The command will fail if the specified VMID does not exist or if the VM/CT is already running. Using <i>--force</i> should be done with extreme care, as it can bypass critical safety checks and potentially lead to data corruption or inconsistent states.


title: OUTPUT BEHAVIOR
content:
The command typically returns immediately after the VM or CT boot process has been initiated on the host. It does not wait for the guest operating system inside the VM/CT to fully boot or become accessible. To check the actual runtime status, use <i>qm status &lt;vmid&gt;</i>.


title: AUTOSTART CONFIGURATION
content:
While <i>qm-start</i> initiates a VM/CT manually, Proxmox VE also provides an autostart feature (usually configured per VM/CT in the GUI or via <i>qm set</i>). This allows VMs/CTs to automatically start with the host system or when the host node reboots, ensuring high availability and ease of management for critical services.


title: HISTORY
content:
The <i>qm-start</i> command is an integral part of the Proxmox Virtual Environment (PVE) command-line interface, which was first released in 2007. As Proxmox VE evolved into a leading open-source virtualization platform, the <i>qm</i> utility became the primary tool for managing QEMU/KVM virtual machines and LXC containers. <i>qm-start</i> has been a core component since the early days, adapting to new features and technologies within the virtualization stack, consistently providing a robust way to bring virtualized workloads online. Its design reflects Proxmox's philosophy of offering powerful, enterprise-grade virtualization management through a straightforward command-line interface.


title: SEE ALSO
content:
<i>qm stop(1)</i> &nbsp; &nbsp; &nbsp; Stop a virtual machine or container gracefully., <i>qm shutdown(1)</i> &nbsp; &nbsp; &nbsp; Request a graceful shutdown of a virtual machine or container., <i>qm status(1)</i> &nbsp; &nbsp; &nbsp; Get the current status of a virtual machine or container., <i>qm list(1)</i> &nbsp; &nbsp; &nbsp; List all virtual machines and containers., <i>qm(1)</i> &nbsp; &nbsp; &nbsp; The main Proxmox VE VM/CT management utility.


title: PARAMETERS
content:
<b><vmid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>unique ID</b> (integer) of the virtual machine whose status is to be queried. This is a <i>mandatory</i> parameter.<br><br><b>--output-format <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired output format. Valid options include <b>json</b>, <b>yaml</b>, <b>text</b>, and <b>pretty-json</b>. This is useful for scripting and programmatic parsing of the VM status.<br><br><b>--verbose <boolean></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <b>1</b> (true), provides more detailed information about the VM's status, such as uptime or specific error messages. If set to <b>0</b> (false) or omitted, a concise status is returned.<br><br>


title: DESCRIPTION
content:
<i>qm status</i> is a subcommand of the <br><b>qm</b> utility, which is a core component of the Proxmox Virtual Environment (PVE). It is used to query the current runtime status of a specific QEMU/KVM virtual machine (VM) managed by Proxmox. This command provides quick and essential information about a VM's operational state, such as whether it is <b>running</b>, <b>stopped</b>, <b>paused</b>, or if an <b>error</b> has occurred.<br><br>System administrators commonly use <i>qm status</i> to get an immediate overview of their VMs without needing to access the Proxmox web interface. It helps in troubleshooting, verifying successful VM startups or shutdowns, and scripting automated monitoring tasks. The output typically includes the VM's power state, and with the <i>--verbose</i> option, it can provide additional details like uptime, and other resource-related information depending on the VM's current state.


title: CAVEATS
content:
This command is <i>specific to Proxmox Virtual Environment (PVE)</i> and is not a general Linux command found on all distributions. Its functionality relies on the underlying Proxmox system architecture for VM management. Users must have appropriate permissions to query VM status. The detailed output obtained with <i>--verbose</i> may vary depending on the VM's exact power state and the version of Proxmox VE being used.


title: COMMON VM STATES
content:
The <i>qm status</i> command can report several common VM power states:<br><b>running</b>: The VM is actively operating.<br><b>stopped</b>: The VM is powered off.<br><b>paused</b>: The VM is temporarily suspended.<br><b>error</b>: An issue has occurred preventing the VM from operating correctly.


title: SCRIPTING AND AUTOMATION
content:
Using the <i>--output-format json</i> or <i>--output-format pretty-json</i> option is highly recommended for scripting and automating VM management tasks. This allows other programs or scripts to easily parse the VM's status and take appropriate actions.


title: HISTORY
content:
The <i>qm</i> command, including its <i>status</i> subcommand, has been an integral part of the Proxmox Virtual Environment since its early versions. Proxmox VE, an open-source server virtualization management solution, was first released in 2007. The <i>qm</i> utility was developed to provide a robust command-line interface for managing QEMU/KVM virtual machines, simplifying tasks such as starting, stopping, and querying the status of VMs. Its design reflects the need for efficient server administration and automation in virtualized environments.


title: PARAMETERS
content:
<b><i>(None)</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>qm-stop</b> command does not accept any command-line options or parameters. Its behavior is entirely dependent on the configuration of the Qmail installation and the process supervision system (e.g., <b>daemontools</b> or <b>runit</b>) it interacts with.<br><br>


title: DESCRIPTION
content:
<b>qm-stop</b> is a utility used to gracefully halt the Qmail mail transfer agent (MTA) daemon and its associated services. When executed, it sends appropriate signals to the running Qmail processes (such as <b>qmail-send</b>, <b>qmail-lspawn</b>, <b>qmail-rspawn</b>, <b>qmail-smtpd</b>, etc.) to ensure a clean shutdown.<br><br>This means that current mail deliveries might complete, and no new mail processing or acceptance will occur until Qmail is restarted. It's a crucial part of managing a Qmail installation, often used before system maintenance, configuration changes, or during troubleshooting to prevent mail loop issues or resource consumption. It relies on the correct setup of Qmail's process supervision mechanisms, commonly handled by <b>daemontools</b> or <b>runit</b>, which ensures that services are stopped in an orderly fashion. It does not directly manage the mail queue; rather, it stops the processes responsible for sending and receiving mail and processing the queue.


title: CAVEATS
content:
<ul><li><b>Prerequisites:</b> This command assumes a functional Qmail installation, typically managed by a process supervision system like <b>daemontools</b> or <b>runit</b>. Without this setup, <b>qm-stop</b> may not function correctly or might not be present.</li><li><b>Permissions:</b> It must be run with appropriate permissions, typically as the <b>root</b> user or a user with privileges to control the Qmail service and its associated processes.</li><li><b>Queue Management:</b> While <b>qm-stop</b> halts the Qmail processes, it does not clear or directly manage the mail queue. Any mail waiting in the queue will remain there until Qmail is restarted.</li><li><b>Supervisor Dependency:</b> Its operation relies on the Qmail services being correctly managed by a supervisor. If Qmail is not running under such a system, <b>qm-stop</b> might fail or report that Qmail is not running.</li></ul>


title: USAGE CONTEXT
content:
<b>qm-stop</b> is typically employed in scenarios requiring a controlled shutdown of the mail system. This includes performing system maintenance (e.g., kernel upgrades, hardware changes), applying Qmail configuration updates, or during troubleshooting to isolate issues by stopping mail flow. It is almost always followed by <b>qm-start</b> after the necessary operations are completed.


title: HISTORY
content:
<b>qm-stop</b> is an integral part of the Qmail suite, a Mail Transfer Agent (MTA) developed by Daniel J. Bernstein (DJB) in the mid-1990s. Qmail was designed with a strong emphasis on security, reliability, and modularity. This modular design often necessitates the use of external process supervision tools like <b>daemontools</b> to manage its various components.<br><br>The <b>qm-stop</b> command emerged as a standard administrative tool within the Qmail ecosystem, providing a consistent and reliable method for administrators to gracefully shut down the mail system. Its usage has remained consistent since the early days of Qmail, reflecting the stable and robust nature of the Qmail architecture and its interaction with process supervisors.


title: PARAMETERS
content:
<b><i>&lt;vmid&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>ID</b> of the virtual machine to suspend.<br><br><b>--todisk <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify whether to suspend the VM to disk (<i>1</i>/<i>true</i>) or to RAM (<i>0</i>/<i>false</i>). Default is <i>1</i> (to disk).<br><br><b>--force <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force suspend the VM, even if its current state might not typically allow it. Use with caution.<br><br><b>--keep-cpu-hotplug-state <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <i>1</i>, keep the CPU hotplug state. Otherwise, reset it after suspend.<br><br><b>--keep-qemu-process <i>&lt;boolean&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If set to <i>1</i>, keep the QEMU process running after the VM state is suspended. Useful for debugging.<br><br>


title: DESCRIPTION
content:
<i>qm-suspend</i> is a utility provided by <b>Proxmox VE</b> to suspend a running <b>QEMU/KVM</b> virtual machine. Suspending a VM involves saving its current state (memory, CPU registers, devices) to a file or keeping it in RAM, allowing it to be resumed later from the exact point it was suspended. This is useful for saving power, freeing up resources temporarily, or for migrating a VM without shutting it down.<br><br>When suspended to disk, the VM's entire state is written to a file, making it persistent even after a host reboot. When suspended to RAM, the state is held in the host's memory, offering faster suspend/resume times but losing the state if the host reboots or loses power. The command requires the VMID (Virtual Machine ID) as a mandatory argument. It's an essential tool for managing the lifecycle of virtual machines in a Proxmox environment, providing flexibility for maintenance, resource optimization, and high availability strategies.


title: CAVEATS
content:
<b>Suspending to RAM</b> (<i>--todisk 0</i>) means the VM state is lost if the host reboots or loses power.<br><b>Suspending large VMs to disk</b> can take significant time and requires sufficient free disk space.<br>Not all applications or workloads inside the VM handle suspension gracefully; active network connections or time-sensitive processes might break.<br>This command is for <b>QEMU/KVM virtual machines only</b>; <b>LXC containers cannot be suspended</b> using <i>qm-suspend</i>.


title: SUSPEND TYPES EXPLAINED
content:
When suspending a VM, you have two primary options: <i>to disk</i> or <i>to RAM</i>. Suspending <i>to disk</i> saves the VM's entire state to a file on the host's storage. This makes the state persistent across host reboots but requires sufficient disk space and can take longer for large VMs. Suspending <i>to RAM</i> keeps the VM's state in the host's memory. This offers much faster suspend and resume times but is volatile; the VM state will be lost if the host loses power or reboots. By default, <i>qm-suspend</i> performs a suspend <i>to disk</i>.


title: RESUMING A SUSPENDED VM
content:
A VM suspended using <i>qm-suspend</i> can be brought back to its exact previous state using the <i>qm resume</i> command. It's important to use <i>qm resume</i> specifically for suspended VMs, rather than <i>qm start</i>, as <i>qm start</i> would boot the VM from scratch, ignoring any suspended state and potentially leading to data inconsistencies.


title: HISTORY
content:
<i>qm-suspend</i> is an intrinsic command within the <b>Proxmox VE</b> virtualization platform, which has been under continuous development since its inception in the mid-2000s. Its functionality directly leverages <b>QEMU/KVM's</b> capabilities for saving and restoring VM states, a feature that has evolved significantly alongside advancements in virtualization technologies. As a core VM lifecycle management tool, it has been available as long as <b>Proxmox VE</b> has supported <b>QEMU/KVM</b>, adapting to new QEMU features and Proxmox management paradigms.


title: PARAMETERS
content:
<b><I>&#x3C;VMID&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The numeric ID of the virtual machine or container that you wish to convert into a template. This ID must correspond to an existing, non-running VM or container.<br><br>


title: DESCRIPTION
content:
The <b>qm template</b> command, a subcommand of <b>qm</b> (Proxmox Virtual Machine command), is used to transform an existing virtual machine (VM) or container into a template. A template is a read-only, non-bootable snapshot of a VM or container, designed to serve as a base for creating new, identical instances quickly and efficiently. By converting a well-configured VM into a template, administrators can streamline the deployment process, ensuring consistency across new deployments and saving significant time compared to installing and configuring each new VM from scratch. Once converted, the original VMID is marked as a template and cannot be started directly; it must be <I>cloned</I> to create a runnable VM.


title: CAVEATS
content:
Once a VM is converted into a template using <b>qm template</b>, it becomes read-only and cannot be started directly. To use the template, it must be <I>cloned</I> into a new virtual machine. There is no direct command to 'un-template' a VM; to revert, one must clone the template back into a standard VM. Ensure the VM is shut down before converting it to a template to avoid data inconsistencies.


title: TYPICAL WORKFLOW
content:
A common use case involves creating a new VM, installing an operating system, applying necessary updates and software, and configuring it to a desired state. Once this 'master' VM is ready, it is shut down, and then the <b>qm template</b> command is executed with its <I>VMID</I> to convert it into a reusable template for future deployments. This ensures that all new VMs based on this template will inherit the pre-configured environment.


title: GUI EQUIVALENT
content:
The functionality of <b>qm template</b> is also accessible via the Proxmox VE web interface. Users can select a VM or container from the tree view, navigate to 'More' (or similar context menu), and choose the 'Convert to Template' option. This performs the same operation as the command-line utility.


title: HISTORY
content:
The ability to manage templates has been a fundamental feature of Proxmox VE since its early versions, reflecting the critical need for rapid and consistent VM deployment in virtualized environments. The <b>qm template</b> command specifically provides a straightforward CLI method for this core functionality, complementing the graphical user interface options for template creation.


title: PARAMETERS
content:
<b>vmid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique identifier (integer) of the virtual machine or container to be unlocked. This ID must correspond to an existing guest on the Proxmox host.<br><br>


title: DESCRIPTION
content:
<i>qm-unlock</i> is a specialized command within the Proxmox Virtual Environment (PVE) ecosystem. Its primary function is to forcibly remove a lock from a virtual machine (VM) or container (CT) that has become stuck in a locked state. <br> <br> Operations like migration, backup, restore, or even starting/stopping a VM/CT can place a temporary lock on the guest to prevent concurrent actions and ensure data integrity. If such an operation fails, is interrupted, or crashes, the lock file might not be properly removed, leaving the VM/CT in an unusable "locked" state. <br> <br> <i>qm-unlock</i> resolves this by manually clearing the lock, allowing administrators to resume operations on the affected guest. It's a critical tool for troubleshooting and recovering from specific Proxmox guest-related issues.


title: CAVEATS
content:
Using <i>qm-unlock</i> requires caution. It should only be used when an operation on the VM/CT has definitively failed or is stuck, and you are certain no background process is still legitimately holding the lock. Forcibly unlocking a VM while an operation is still actively running (even if slow) can lead to data corruption, file system inconsistencies, or other severe issues. Always verify the state of the VM/CT and any pending operations before using this command.


title: CHECKING LOCK STATUS
content:
Before using <i>qm-unlock</i>, it is highly recommended to check the VM's status using <b>qm status <vmid></b> or through the Proxmox web interface. The web interface will often show a "locked" icon or message next to the VM.


title: PROXMOX CONTEXT
content:
This command is specific to Proxmox VE and is not a general Linux utility. It relies on Proxmox's internal management mechanisms and file structures for locking.


title: HISTORY
content:
<i>qm-unlock</i> is an integral part of the Proxmox Virtual Environment (PVE), a Debian-based open-source server virtualization management solution. As PVE evolved to provide robust management for KVM virtual machines and LXC containers, the need arose for a utility to handle orphaned locks that could occur due to unexpected system reboots, failed operations, or network issues. <i>qm-unlock</i> was developed as a direct solution to this common administrative challenge, ensuring the stability and manageability of virtual guests within the Proxmox ecosystem. It has been a standard utility within Proxmox for many versions, reflecting the practical needs of system administrators.


title: SYNOPSIS
content:
<b>qm-vncproxy</b> <I>&#x3C;vmid&#x3E;</I> [<b>--listen</b> <I>&#x3C;IP_ADDRESS&#x3E;</I>] [<b>--port</b> <I>&#x3C;PORT&#x3E;</I>] [<b>--vnc</b> <I>&#x3C;VNC_PORT&#x3E;</I>] [<b>--websocket</b> <I>&#x3C;0|1&#x3E;</I>] [<b>--path</b> <I>&#x3C;PATH&#x3E;</I>] [<b>--ssl-cert</b> <I>&#x3C;FILE&#x3E;</I>] [<b>--ssl-key</b> <I>&#x3C;FILE&#x3E;</I>] [<b>--daemon</b>] [<b>--verbose</b>]


title: PARAMETERS
content:
<b><I>&#x3C;vmid&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The unique numeric ID of the virtual machine or container for which VNC access is being proxied.<br><br><b><b>--listen</b> <I>&#x3C;IP_ADDRESS&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the IP address on which the proxy should listen for incoming client connections. Defaults to '127.0.0.1' (localhost) for internal Proxmox UI use.<br><br><b><b>--port</b> <I>&#x3C;PORT&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the TCP port number on which the proxy will listen for client connections (e.g., from a web browser). This is the external-facing port.<br><br><b><b>--vnc</b> <I>&#x3C;VNC_PORT&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the port on which the guest's internal VNC server is listening. This is the internal port on the VM/CT accessible from the Proxmox host.<br><br><b><b>--websocket</b> <I>&#x3C;0|1&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables (1) or disables (0) WebSocket proxying. This is crucial for seamless integration with modern web browsers and the Proxmox web UI. It is typically enabled by default.<br><br><b><b>--path</b> <I>&#x3C;PATH&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the URL path for WebSocket connections, e.g., '/websockify'. This option is relevant when integrating with specific web server configurations or reverse proxies.<br><br><b><b>--ssl-cert</b> <I>&#x3C;FILE&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the path to the SSL certificate file (e.g., in PEM format) to enable encrypted WebSocket connections (WSS) between the client and the proxy.<br><br><b><b>--ssl-key</b> <I>&#x3C;FILE&#x3E;</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the path to the SSL private key file corresponding to the SSL certificate, used for establishing encrypted WebSocket connections (WSS).<br><br><b><b>--daemon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the <i>qm-vncproxy</i> process in the background as a daemon, detaching it from the controlling terminal.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed logging and debugging information to the console or log files.<br><br>


title: DESCRIPTION
content:
<i>qm-vncproxy</i> is a fundamental utility within Proxmox Virtual Environment (PVE) that acts as a secure VNC proxy for both KVM virtual machines and LXC containers. Its primary function is to facilitate in-browser console access, an integral part of the Proxmox web interface. When a user requests a graphical console session through the PVE UI, <i>qm-vncproxy</i> establishes a secure WebSocket connection (often SSL/TLS encrypted) between the user's web browser and the Proxmox host. It then intelligently bridges and forwards the VNC traffic originating from the guest's internal VNC server to the browser. This architecture eliminates the need for users to install a dedicated VNC client, significantly enhancing security by centralizing access control through the robust PVE authentication system and simplifying connectivity management.


title: CAVEATS
content:
While <i>qm-vncproxy</i> enhances VNC security by centralizing access through the Proxmox authentication system, direct exposure of the proxy to the public internet without proper firewall rules, SSL/TLS encryption, and a robust reverse proxy is highly discouraged. It is primarily designed to operate behind the Proxmox web interface's authentication layer. Each active VNC proxy session consumes system resources (CPU, RAM, network bandwidth) on the Proxmox host. Ensure network configuration permits traffic to the proxy port if access is required from external networks.


title: WEBSOCKET AND NOVNC INTEGRATION
content:
<i>qm-vncproxy</i> fundamentally relies on WebSocket technology to translate the traditional VNC protocol into a format consumable by web browsers. This integration, often powered by or compatible with the underlying principles of the <i>noVNC</i> project, is critical for its role in providing a 'clientless' console experience directly within the Proxmox web user interface, enhancing accessibility and ease of use.


title: AUTHENTICATION CONTEXT
content:
It is crucial to understand that <i>qm-vncproxy</i> typically operates within a pre-authenticated context. It does not perform user authentication itself. Instead, it is invoked by the Proxmox web interface on behalf of a user who has already successfully authenticated and been authorized to access the specific virtual machine or container. This design delegates the crucial security and access control responsibilities to the comprehensive Proxmox authentication and authorization system.


title: HISTORY
content:
<i>qm-vncproxy</i>'s development is closely intertwined with the evolution of web-based virtualization management interfaces, particularly within the Proxmox Virtual Environment (PVE) ecosystem. As modern web applications moved towards providing rich, interactive experiences without requiring external client software, components like <i>qm-vncproxy</i> became indispensable. It emerged as a solution to bridge the traditional VNC protocol with WebSocket technology, often leveraging projects like noVNC, enabling seamless in-browser console access. This marked a significant step in Proxmox VE's commitment to delivering an integrated, secure, and user-friendly virtualization platform, evolving from simpler direct VNC forwarding methods to a more robust and integrated proxy solution over the platform's history.


title: SYNOPSIS
content:
qm-wait &lt;upid&gt; [--timeout &lt;integer&gt;] [--quiet] [--verbose] [--max-log-lines &lt;integer&gt;] [--output-format &lt;json|text&gt;]


title: PARAMETERS
content:
<b>upid</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <I>Unique Process IDentifier</I> of the task to wait for. This is a string identifying a background task on a Proxmox VE node.<br><br><b>--timeout &lt;integer&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Maximum number of seconds to wait for the task to complete. If the task does not finish within this period, the command will exit with a timeout error.<br><br><b>--quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress normal success messages. Only error messages are printed.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print more detailed information about the task's progress and status during the wait.<br><br><b>--max-log-lines &lt;integer&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When the task fails, display up to this many lines from the end of the task log.<br><br><b>--output-format &lt;json|text&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define the output format for the final result of the UPID. Can be <I>json</I> or <I>text</I>.<br><br>


title: DESCRIPTION
content:
<b>qm-wait</b> is a utility command used within Proxmox VE environments. Its primary function is to block execution until a specified background task (identified by its <I>Unique Process IDentifier</I>, or <I>UPID</I>) has completed. This is particularly useful in scripting and automation where subsequent actions depend on the successful or failed completion of a VM or container operation (e.g., starting, stopping, migrating, or backing up a VM/CT). The command monitors the status of the given UPID, exiting successfully (return code 0) once the task finishes, or with an error code if the task fails, times out, or the UPID is invalid. It allows for robust error handling and sequential task management in Proxmox scripts.


title: CAVEATS
content:
<b>qm-wait</b> relies on the UPID being valid and existing. If the UPID is incorrect or the task has already completed/disappeared from the task history, <b>qm-wait</b> might exit immediately or report an error. It is a blocking command, so in scripts, ensure proper timeout handling to prevent indefinite waiting. This command is specific to Proxmox VE environments.


title: UNDERSTANDING UPIDS
content:
A <I>Unique Process IDentifier</I> (<b>UPID</b>) is a unique string that identifies a background task in Proxmox VE. It typically has the format <I>UPID:node:timestamp:taskid:user@realm:vmtype:vmid:command:</I>. Commands like <I>qm start</I> or <I>pct migrate</I> return a UPID, which can then be passed to <b>qm-wait</b> to monitor its completion.


title: SCRIPTING AND AUTOMATION
content:
<b>qm-wait</b> is invaluable for scripting automated Proxmox VE tasks. For instance, after initiating a VM migration with <I>qm migrate</I> (which returns a UPID), a script can use <b>qm-wait</b> with that UPID to ensure the migration is complete before attempting subsequent actions like VM power-off or backup. This ensures proper sequencing and error handling in automated workflows.


title: HISTORY
content:
<b>qm-wait</b> is an integral part of the Proxmox VE suite, a leading open-source virtualization management solution. It emerged as a necessary utility to manage asynchronous operations (like VM starts, migrations, backups) which are handled as background tasks identified by <I>UPIDs</I>. Its development is deeply tied to Proxmox's robust task management system, enabling reliable automation and scripting of long-running operations within the Proxmox ecosystem.


title: SYNOPSIS
content:
<B>qmake</B> [<I>options</I>] [<I>files</I>]<br>Common usages:<br><B>qmake -project</B> [<I>options</I>]<br><B>qmake</B> [<I>file.pro</I>] [<I>options</I>]<br><B>qmake -makefile</B> [<I>file.pro</I>] [<I>options</I>]


title: PARAMETERS
content:
<b><b>-project</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a basic <I>.pro</I> project file in the current directory. Ideal for starting new projects.<br><br><b><b>-o</b> <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output build file (e.g., Makefile, .vcxproj). If omitted, <I>qmake</I> uses a default name.<br><br><b><b>-makefile</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <I>qmake</I> to generate a Makefile. This is the default behavior when a <I>.pro</I> file is provided.<br><br><b><b>-spec</b> <I>spec</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target platform and compiler configuration (e.g., <I>linux-g++</I>, <I>win32-msvc</I>). Use <I>qmake -query QMAKE_SPEC</I> to see current spec.<br><br><b><b>-config</b> <I>config</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a specific build configuration to the project (e.g., <I>debug</I>, <I>release</I>, <I>static</I>, <I>shared</I>). Can be used multiple times.<br><br><b><b>-set</b> <I>VAR</I>=<I>VALUE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a <I>qmake</I> variable before processing the project file. Useful for overriding project settings from the command line.<br><br><b><b>-query</b> [<I>VAR</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Queries the value of a <I>qmake</I> variable or lists all known variables if no variable is specified.<br><br><b><b>-r</b>, <b>-recursive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively processes subdirectories specified in the <I>SUBDIRS</I> variable of the project file.<br><br><b><b>-nocache</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the <I>qmake</I> cache, forcing it to re-evaluate all expressions.<br><br><b><b>-help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available command-line options.<br><br><b><b>-v</b>, <b>-version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <I>qmake</I> version and Qt version information.<br><br><b><b>-d</b>, <b>-debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output, showing more detailed information about <I>qmake</I>'s processing.<br><br><b><b>-Wall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables all compiler warnings. This is often passed through to the underlying compiler.<br><br>


title: DESCRIPTION
content:
<I>qmake</I> is a cross-platform build system generator used primarily with the Qt framework. Its main purpose is to simplify the compilation process of Qt-based applications and libraries across various operating systems and compiler environments. Instead of manually writing complex Makefiles or project files for each platform, developers use <I>qmake</I> to process simple, declarative project files (typically ending in <I>.pro</I>).<br><br><I>qmake</I> automatically handles common Qt-specific build steps, such as invoking the Meta-Object Compiler (<I>moc</I>) for signals and slots, the User Interface Compiler (<I>uic</I>) for <I>.ui</I> files, and the Resource Compiler (<I>rcc</I>) for embedding resources. It can generate Makefiles (for Unix-like systems, MinGW), Visual Studio project files (for Windows), Xcode project files (for macOS), and more. This automation significantly streamlines development by abstracting away platform-specific build complexities, allowing developers to focus on writing code.


title: CAVEATS
content:
While powerful for Qt projects, <I>qmake</I> is less suitable or efficient for general C++ projects without Qt dependencies. For new Qt projects, especially starting with Qt 6 and beyond, <B>CMake</B> is increasingly recommended as the preferred build system, offering greater flexibility and a more standardized approach within the broader C++ ecosystem. <I>qmake</I> projects can sometimes become complex and harder to maintain for very large or highly customized build scenarios compared to alternatives.


title: <B>QMAKE PROJECT FILES (.PRO)</B>
content:
The core of <I>qmake</I> are its project files, typically named <I>.pro</I>. These text files use a simple, declarative syntax to define project properties like source files (<B>SOURCES</B>), header files (<B>HEADERS</B>), Qt modules (<B>QT</B>), build configurations (<B>CONFIG</B>), and platform-specific settings. <I>qmake</I> reads these files and translates them into appropriate build system files for the target platform.


title: <B>VARIABLES AND FUNCTIONS</B>
content:
<I>qmake</I> allows extensive configuration through variables (e.g., <B>TARGET</B>, <B>DESTDIR</B>, <B>INCLUDEPATH</B>, <B>LIBS</B>) and functions (e.g., <B>message()</B>, <B>system()</B>, <B>contains()</B>, <B>$$[QT_INSTALL_HEADERS]</B>). These provide powerful ways to manage dependencies, define custom build steps, and adapt projects to different environments or build requirements.


title: HISTORY
content:
<I>qmake</I> was originally developed by Trolltech (the creators of Qt, later acquired by Nokia, then by Digia, and now managed by The Qt Company) as an integral part of the Qt toolkit. It was introduced to address the complexities of building cross-platform C++ applications, particularly those leveraging Qt's extensive features. For many years, <I>qmake</I> served as the primary and recommended build system for all Qt development. While it remains fully supported for existing projects, The Qt Company has increasingly moved towards advocating for <B>CMake</B> as the default build system for new Qt projects, especially since Qt 6, due to CMake's broader adoption in the C++ community and its more powerful, flexible features.


title: SEE ALSO
content:
<b>make(1)</b>: The standard build automation tool that <I>qmake</I> often generates files for., <b>cmake(1)</b>: A widely adopted cross-platform build system generator, becoming the recommended choice for modern Qt projects., <b>moc(1)</b>: Qt's Meta-Object Compiler, invoked by <I>qmake</I> to handle C++ extensions for Qt's signal/slot mechanism., <b>uic(1)</b>: Qt's User Interface Compiler, invoked by <I>qmake</I> to compile <I>.ui</I> files (Qt Designer forms) into C++ code., <b>rcc(1)</b>: Qt's Resource Compiler, invoked by <I>qmake</I> to compile <I>.qrc</I> files (Qt resource files) into C++ code., <b>qtchooser(1)</b>: A utility to select the default Qt installation to be used by development tools like <I>qmake</I>.


title: PARAMETERS
content:
<b><i>-p</i>, <i>--play</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Play</b> current track.<br><br><b><i>-s</i>, <i>--stop</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Stop</b> playback.<br><br><b><i>-t</i>, <i>--play-pause</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Toggle play/pause</b> state.<br><br><b><i>-n</i>, <i>--next</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Play next</b> track in playlist.<br><br><b><i>-r</i>, <i>--previous</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Play previous</b> track in playlist.<br><br><b><i>-f</i>, <i>--show-hide</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Show or hide</b> the main player window.<br><br><b><i>-a</i>, <i>--add-file <file></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Add specified file</b> to the playlist.<br><br><b><i>-l</i>, <i>--add-url <url></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Add specified URL</b> (e.g., streaming radio) to the playlist.<br><br><b><i>-c</i>, <i>--clear</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Clear</b> the current playlist.<br><br><b><i>-v</i>, <i>--volume <value></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Set volume</b> to a value between 0 and 100.<br><br><b><i>-q</i>, <i>--quit</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Quit</b> the player application.<br><br><b><i>--enqueue</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Enqueue files</b> specified as arguments instead of replacing the playlist.<br><br><b><i>--toggle-playlist</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Show or hide</b> the playlist window.<br><br><b><i>--toggle-equalizer</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Show or hide</b> the equalizer window.<br><br><b><i>--toggle-lyrics</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Show or hide</b> the lyrics window.<br><br><b><i>--playback-mode <mode></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Set playback mode</b> (0-repeat, 1-repeat_playlist, 2-track, 3-random).<br><br><b><i>--repeat</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Toggle repeat</b> mode.<br><br><b><i>--shuffle</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Toggle shuffle</b> mode.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Print version information</b> about Qmmp.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Print help information</b> and usage details.<br><br>


title: DESCRIPTION
content:
Qmmp is a <i>cross-platform multimedia player</i> built using the <b>Qt framework</b>, offering a user interface highly reminiscent of popular classic players like Winamp and XMMS. It is primarily designed for <i>audio playback</i>, supporting a wide array of formats including MP3, Ogg Vorbis, FLAC, WAV, and more, often extensible via its robust <b>plugin system</b>.<br>This modular architecture allows for customization of input/output, audio effects, visualizations, and general functionality. Users can further personalize their experience through <i>skins and themes</i>. Qmmp is known for being <i>lightweight, efficient</i>, and provides a comprehensive set of features for managing and enjoying music collections, making it a favorite among users seeking a classic player feel with modern capabilities.


title: CAVEATS
content:
Qmmp relies heavily on <b>Qt libraries</b> for its graphical interface and core functionality.<br>While highly extensible via <i>plugins</i>, specific audio formats or output methods may require the installation of corresponding plugin packages.


title: PLUGIN SYSTEM
content:
Qmmp boasts a <i>highly modular architecture</i> implemented through a rich <b>plugin system</b>.<br>This allows users to extend its capabilities significantly, including support for various audio codecs, sound output methods (like ALSA, PulseAudio, OSS), digital signal processing (DSP) effects, audio visualizations, and integration with online services. Users can install and enable/disable plugins via the application's preferences.


title: SKINS AND THEMES
content:
One of Qmmp's defining features is its extensive support for <b>skins and themes</b>, allowing users to dramatically change the player's appearance.<br>It supports both <i>Winamp-compatible classic skins</i> and its own native skins, enabling deep personalization of the user interface.


title: HISTORY
content:
Qmmp emerged as a modern <b>Qt-based alternative</b> to beloved classic audio players like <i>Winamp and XMMS</i>, aiming to provide a similar user experience on cross-platform environments.<br>Its development began with a focus on delivering a lightweight yet feature-rich audio player with extensive <i>customization capabilities</i> through skins and a modular plugin system. It has been under active development, evolving to support contemporary audio standards while retaining its nostalgic interface appeal.


title: PARAMETERS
content:
<b><backup_file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>The path to the backup archive. This can be <br> a local file path (e.g., <i>/var/lib/vz/dump/vzdump-qemu-100-2023_10_26-12_00_00.vma.gz</i>) <br> or a reference to a backup on a Proxmox storage <br> (e.g., <i>local:backup/vzdump-qemu-100-2023_10_26-12_00_00.vma.gz</i>).<br><br><b><target_vmid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>The virtual machine ID for the restored guest. <br> This can be a new, unused ID, or an existing one if <br> used with the <i>--force</i> option.<br><br><b>--storage <storage_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Specifies the target storage for the virtual machine's disks. <br> This can be the ID of any configured storage in Proxmox VE <br> (e.g., <i>local-lvm</i>, <i>cephfs</i>, <i>nfs-storage</i>).<br><br><b>--format <format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Sets the disk image format for the restored disks. <br> Supported formats include <i>raw</i>, <i>qcow2</i>, or <i>vmdk</i>. <br> Defaults to the format from the backup if not specified.<br><br><b>--name <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Assigns a new name to the restored virtual machine. <br> If not specified, the VM will be named using its ID.<br><br><b>--pool <pool_id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Assigns the restored virtual machine to a specific <br> resource pool after creation.<br><br><b>--cores <count></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Sets the number of CPU cores for the restored VM.<br><br><b>--memory <size></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Defines the amount of memory in MiB for the restored VM.<br><br><b>--disk <size_spec></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Allows resizing the main disk of the VM during restore. <br> For example, <i>scsi0=size=30G</i>. <br> Only applicable for VMA backups and can increase or decrease size.<br><br><b>--network <nic_mapping></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Provides mapping for network interfaces. <br> For example, <i>--network 'net0=name=eth0,bridge=vmbr1'</i>. <br> Useful when the target network configuration differs.<br><br><b>--start</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Automatically starts the virtual machine after a <br> successful restore operation.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Forces the restore operation even if the <i>target_vmid</i> <br> already exists, potentially overwriting an existing VM. <br> <b>Use with extreme caution!</b><br><br><b>--dryrun</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Performs a dry run, showing what the command would do <br> without actually restoring the VM. <br> Useful for testing configurations.<br><br>


title: DESCRIPTION
content:
<i>qmrestore</i> is a command-line utility within the <br> Proxmox Virtual Environment (PVE) suite, specifically designed <br> for restoring KVM (Kernel-based Virtual Machine) guests from <br> existing backup archives. It serves as a crucial tool for <br> disaster recovery, system migration, or creating clones of <br> virtual machines. The command takes a backup file, typically <br> created by the <br> <i>vzdump</i> utility, and unpacks its contents <br> to recreate a fully functional virtual machine. <br><br>It supports various backup formats, including the default <br> Proxmox-specific <br> <b>VMA (Virtual Machine Archive)</b> format, <br> which is highly optimized for efficiency. <br> <i>qmrestore</i> can place the restored VM's disks <br> on different storage types supported by Proxmox VE, <br> such as local directories, LVM-Thin, ZFS, Ceph, <br> NFS, or iSCSI. Users can specify a new VMID for the <br> restored guest, or overwrite an existing one (with caution). <br> Furthermore, it provides extensive options to modify the <br> restored VM's configuration, such as CPU cores, memory, <br> disk format, network interface mappings, and more, <br> allowing for flexible deployments and adjustments <br> to the target environment.


title: CAVEATS
content:
<i>qmrestore</i> is an integral part of Proxmox VE and <br> requires a running Proxmox VE host to function. <br><br><b>Permissions:</b> Users must have appropriate <br> permissions on the Proxmox VE host to perform <br> restore operations, including access to the backup <br> storage and the target storage for the VM's disks. <br><br><b>Disk Space:</b> Adequate free disk space on the <br> specified target storage is critical for a successful restore. <br> Insufficient space will lead to failure. <br><br><b>VMID Conflicts:</b> Restoring to an existing VMID <br> without the <i>--force</i> option will result in an error. <br> Using <i>--force</i> will completely overwrite the existing VM, <br> leading to data loss if not intended. <br><br><b>Hardware Differences:</b> If restoring to different <br> hardware, adjustments to network configuration via <br> <i>--network</i> or SCSI controller types via <br> <i>--scsihw</i> might be necessary to ensure the <br> restored VM boots correctly.


