# CommandSection

title: DESCRIPTION
content:
<i>convert</i> is a fundamental command-line utility from the <i>ImageMagick</i> suite. It serves as a versatile tool for processing digital images, enabling users to transform formats (e.g., JPEG to PNG, TIFF to WebP), resize dimensions, rotate orientations, crop sections, and apply various artistic or technical effects.<br>Its strength lies in supporting a vast array of image formats and its non-interactive nature, making it ideal for scripting and batch operations on servers or local systems. From simple format changes to complex image compositions, <i>convert</i> provides extensive control over image attributes and pixel data.


title: CAVEATS
content:
The <i>convert</i> command, while highly powerful, can be resource-intensive, especially when processing large images or performing complex operations in batch.<br>Its extensive range of options contributes to a steep learning curve, and understanding the order of operations, especially with multiple inputs or parenthesized commands, requires careful attention.<br>Crucially, with the release of <i>ImageMagick 7</i> (IM7), the standalone <i>convert</i> command is considered <b>deprecated</b> in favor of the unified <i>magick</i> command. While <i>convert</i> often remains available for backward compatibility, new development should ideally use <i>magick</i>.


title: PERFORMANCE CONSIDERATIONS
content:
For very large-scale or high-performance image processing pipelines, while <i>convert</i> is powerful, users might consider alternatives like <i>GraphicsMagick</i> (a fork of ImageMagick 5) or dedicated image processing libraries that might offer different performance characteristics for specific tasks or environments.


title: SCRIPTING UTILITY
content:
Due to its robust command-line interface, <i>convert</i> is extensively used in shell scripts, cron jobs, and server-side applications for automated image handling. Common uses include generating thumbnails, applying watermarks, converting image formats for web optimization, or creating dynamic image content.


title: HISTORY
content:
The <i>convert</i> command has been a cornerstone of the <i>ImageMagick</i> suite since its inception in <b>1990</b>. Initially developed by John Cristy at DuPont, ImageMagick and its utilities like <i>convert</i> quickly became an industry standard for command-line image processing due to their versatility and cross-platform compatibility.<br>It gained significant traction in web development for on-the-fly image manipulation and server-side automation.<br>With the major architectural changes introduced in <i>ImageMagick 7</i>, released around 2016, the design philosophy shifted towards a unified <i>magick</i> command. Consequently, <i>convert</i> and other separate utilities (like <i>mogrify</i>, <i>identify</i>) are now symbolically linked or aliased to <i>magick</i> for backward compatibility, marking a transition in its historical usage.


title: PARAMETERS
content:
<b><I>input-file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the source image file. Can also be a glob pattern, a URL, or <I>-</I> for standard input.<br><br><b><I>output-file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the destination image file. The extension usually determines the output format, or <I>-</I> for standard output.<br><br><b>-resize <I>geometry</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales an image. <I>geometry</I> examples: <I>120x120!</I> (exact size), <I>50%</I> (percentage), <I>x200</I> (height only).<br><br><b>-crop <I>geometry</I>[<I>+offset</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extracts a rectangular region from the image. <I>geometry</I> example: <I>100x150+10+20</I> (width x height at x,y offset).<br><br><b>-rotate <I>degrees</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates the image by the specified <I>degrees</I> (e.g., <I>90</I>, <I>270</I>).<br><br><b>-format <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies the output image <I>format</I> (e.g., <I>jpg</I>, <I>png</I>, <I>gif</I>).<br><br><b>-quality <I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the compression <I>value</I> for lossy formats (JPEG, MIFF, PNG) from 0 (lowest) to 100 (highest quality).<br><br><b>-background <I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the canvas <I>color</I> used for operations like <I>-extent</I> or <I>-rotate</I> when new areas are exposed.<br><br><b>-extent <I>geometry</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the image size and fills any newly exposed areas with the background color. Used for padding or cropping.<br><br><b>-strip</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Strips all profiles, comments, and metadata from the image, reducing file size.<br><br><b>-monochrome</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Converts the image to pure black and white pixels.<br><br><b>-type <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the image <I>type</I> (e.g., <I>Grayscale</I>, <I>TrueColor</I>, <I>Palette</I>).<br><br><b>-composite</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overlays images. Requires multiple input images or a separate overlay image, often combined with <I>-geometry</I> and <I>-gravity</I>.<br><br><b>-draw <I>drawing-string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Draws shapes or text on the image using a specific <I>drawing-string</I> syntax (e.g., <I>'rectangle 10,10 50,50'</I>).<br><br><b>-annotate <I>geometry</I> <I>text</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Annotates the image with <I>text</I> at a specified <I>geometry</I> (position and rotation).<br><br><b>-font <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <I>font</I> to use for text operations like <I>-annotate</I> or <I>-draw</I>.<br><br><b>-gravity <I>direction</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the initial <I>gravity</I> (e.g., <I>NorthWest</I>, <I>Center</I>) for text and image placement.<br><br><b>-density <I>WxH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the image <I>density</I> for rasterizing vector formats (e.g., <I>300x300</I> for 300 DPI).<br><br><b>-flatten</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Merges all layers of a multi-layer image into a single, flat image.<br><br><b>-blur <I>radius</I>x<I>sigma</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a Gaussian blur filter to the image.<br><br><b>-gamma <I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction to the image.<br><br><b>-trim</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes any edges that are the same color as the corner pixels.<br><br><b>-level <I>black_point</I>,<I>white_point</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the image levels by mapping pixel values.<br><br><b>-threshold <I>value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces pixels to be either black or white based on a threshold <I>value</I>.<br><br><b>-auto-orient</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically rotates the image based on EXIF orientation tag.<br><br>


title: DESCRIPTION
content:
<b>convert</b> is a versatile command-line utility from the <I>ImageMagick</I> suite, renowned for its ability to convert images between formats, resize, crop, rotate, and apply numerous graphical effects. It supports over 200 image formats, including common ones like <I>JPEG</I>, <I>PNG</I>, <I>GIF</I>, <I>TIFF</I>, <I>BMP</I>, <I>SVG</I>, and <I>PDF</I>. The <I>convert.im6</I> variant specifically refers to <I>ImageMagick</I> version 6, which was a widely adopted and stable release. It empowers users to perform complex image processing tasks through powerful scripting, making it an indispensable tool for automating image workflows in Linux environments. From simple format changes to intricate composite operations, <b>convert</b> offers robust control over image attributes and pixel data.


title: CAVEATS
content:
<I>convert</I> is part of <I>ImageMagick</I> version 6. In <I>ImageMagick</I> 7, it is deprecated in favor of the unified <I>magick</I> command (e.g., <I>magick convert ...</I> or simply <I>magick ...</I>).<br>The order of operations matters significantly, as <I>convert</I> processes options sequentially from left to right.<br>It can be resource-intensive for very large images or complex, chained operations, potentially consuming significant memory and CPU.


title: IMAGEMAGICK VS. GRAPHICSMAGICK
content:
While <I>convert</I> exists in both <I>ImageMagick</I> and <I>GraphicsMagick</I> (a fork of <I>ImageMagick</I> from 2002), the <I>convert.im6</I> explicitly refers to <I>ImageMagick</I> version 6. Their command-line syntax and capabilities can differ slightly, so it's important to know which suite is being used to ensure correct behavior.


title: PIPING AND STANDARD I/O
content:
<I>convert</I> can read image data from standard input by specifying <I>-</I> as the <I>input-file</I>, and write to standard output by specifying <I>-</I> as the <I>output-file</I>. This enables powerful piping operations in shell scripts, allowing <I>convert</I> to be part of a larger processing pipeline (e.g., <I>cat image.png | convert - -resize 50% | display -</I>).


title: HISTORY
content:
<I>ImageMagick</I>, and by extension <I>convert</I>, was first developed in 1987 by John Cristy. It quickly became a foundational tool for image processing on Unix-like systems. Version 6 of <I>ImageMagick</I>, often referenced by <I>.im6</I> (e.g., in <I>convert.im6</I>), was a highly stable and widely adopted release, where <I>convert</I> served as the primary command-line utility for image transformation. In 2016, <I>ImageMagick</I> 7 introduced a significant architectural change, consolidating most functionalities under a single <I>magick</I> command. While <I>convert</I> is technically deprecated in version 7, it often remains available (e.g., as a symlink to <I>magick</I>) for backward compatibility with existing scripts and workflows.


title: PARAMETERS
content:
<b>-f ENCODING_FROM</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the current character encoding of the filenames that need to be converted.<br><br><b>-t ENCODING_TO</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target character encoding to which filenames should be converted.<br><br><b>-r, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Recursively converts filenames in subdirectories as well as the specified directory.<br><br><b>--notest</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs the actual filename conversion. By default, <b>convmv</b> operates in dry-run mode, only showing what it <I>would</I> do.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly enables dry-run mode. This is the default behavior and shows changes without applying them.<br><br><b>--list-encodings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available character encodings that <b>convmv</b> supports for conversion.<br><br><b>--replace</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Replaces characters that cannot be converted to the target encoding with a specified or default placeholder character (e.g., '?').<br><br><b>-i, --interactive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompts for confirmation before converting each individual file.<br><br><b>--log FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Logs all changes made to filenames, including successful conversions and errors, to the specified file.<br><br>


title: DESCRIPTION
content:
<b>convmv</b> is a utility for converting filenames to a different character encoding. It's particularly useful when dealing with files created on systems using different character encodings (e.g., ISO-8859-1, EUC-JP) and you need to display or use them correctly on a system primarily using UTF-8. It does <I>not</I> convert the content of files, only their names.<br><br>The command offers a dry-run mode by default, allowing users to preview the changes before applying them, which is crucial given the potential impact on filenames. It can operate on individual files, directories, or recursively convert all filenames within a directory tree, making it a powerful tool for migrating entire file systems or large archives between systems with differing locale settings. It leverages underlying encoding conversion libraries to perform its task reliably.


title: CAVEATS
content:
Always perform a dry-run first (the default behavior) to preview changes, as filename alterations can be irreversible.<br>It is <I>highly recommended</I> to create a backup of your data before running <b>convmv</b> with the <I>--notest</I> option.<br>Remember, <b>convmv</b> only changes filenames, not the content of the files themselves.<br>Filenames with severely corrupted or completely unknown original encodings might not be fully recoverable.


title: DEFAULT DRY-RUN MODE
content:
By default, <b>convmv</b> operates in a 'dry-run' mode, meaning it will only show you which filenames would be converted without making any actual changes. This is a crucial safety feature to verify the intended outcome before committing changes. To apply the changes, you must explicitly use the <I>--notest</I> option.


title: ENCODING DETECTION AND SPECIFICITY
content:
While <b>convmv</b> can sometimes intelligently detect broken UTF-8 sequences and try to guess the original encoding, it is always safer and more reliable to explicitly specify both the source (<I>-f</I>) and target (<I>-t</I>) encodings when you know them, to ensure accurate conversions.


title: HISTORY
content:
<b>convmv</b> was developed to address the common and often frustrating problem of character encoding mismatches, particularly relevant when migrating files between different operating systems or locales. As UTF-8 became the predominant encoding in modern Linux distributions, tools like <b>convmv</b> became essential for cleaning up 'garbled' or incorrectly displayed filenames originating from systems using older encodings like ISO-8859-1 or various Windows code pages, simplifying file management and data integrity.


title: SYNOPSIS
content:
<b>cookiecutter</b> [OPTIONS] &lt;template_source&gt;<br><br><i>&lt;template_source&gt;</i>: A URL (e.g., Git repository) or local path to a Cookiecutter template.


title: PARAMETERS
content:
<b><b>--no-input</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt for input; use default values or values from replay.<br><br><b><b>--checkout</b> <i>&lt;branch|tag|commit&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The branch, tag, or commit to checkout after cloning the template.<br><br><b><b>--output-dir</b> <i>&lt;directory&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Where to output the generated project.<br><br><b><b>--config-file</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom user configuration file instead of the default.<br><br><b><b>--default-config</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not load any user configuration file; use only default settings.<br><br><b><b>--overwrite-if-exists</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrite the contents of the output directory if it already exists.<br><br><b><b>--skip-if-file-exists</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip over existing files, do not overwrite them during generation.<br><br><b><b>--replay</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not prompt for input; use the last-used input from the replay file.<br><br><b><b>--skip-replay</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not use the last-used input from the replay file; prompt for new input.<br><br><b><b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show verbose debug logging output.<br><br><b><b>--directory</b> <i>&lt;dirname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Relative path to the template directory within the repository.<br><br>


title: DESCRIPTION
content:
<i><b>cookiecutter</b></i> is a powerful command-line utility designed to automate the scaffolding of new projects from pre-defined templates. It allows developers to quickly create consistent project structures, boilerplate code, and configuration files, significantly accelerating initial project setup. Users provide a template's Git repository URL or local file path.<br><br>Upon invocation, <i><b>cookiecutter</b></i> reads the <i><b>cookiecutter.json</b></i> file located within the template, which specifies a set of variables (e.g., project name, author, license). It then interactively prompts the user for values for these variables. Once all necessary input is collected, <i><b>cookiecutter</b></i> leverages the Jinja2 templating engine to render the template files, replacing variable placeholders with the user-provided data. The final output is a new project directory structured according to the template, containing all the generated files. This tool promotes uniformity across projects, minimizes manual setup errors, and is widely adopted for maintaining best practices across diverse programming ecosystems, particularly within the Python community.


title: CAVEATS
content:
Template quality and maintenance can vary widely, potentially leading to outdated or poorly structured projects.<br>Updates to the original template do not automatically propagate to projects already generated from it.<br>Requires <i><b>git</b></i> to be installed and accessible for cloning templates from remote repositories.<br>Creating sophisticated templates with complex hooks and conditional logic can be challenging.


title: TEMPLATE STRUCTURE
content:
A <i><b>cookiecutter</b></i> template is essentially a directory containing project files and a mandatory <i><b>cookiecutter.json</b></i> file. This JSON file defines the variables that <i><b>cookiecutter</b></i> will prompt the user for, along with their default values. Within the template's files, Jinja2 templating syntax (e.g., <i>{{cookiecutter.project_slug}}</i>) is used to embed these variables, which are replaced during project generation.


title: HOOKS
content:
<i><b>cookiecutter</b></i> supports 'hooks' – Python scripts that can be executed before or after the project generation. Files named <i><b>pre_gen_project.py</b></i> and <i><b>post_gen_project.py</b></i> (located in the template's hooks directory) are automatically run at the respective stages, enabling custom logic like validating inputs, initializing Git repositories, installing dependencies, or printing custom messages.


title: HISTORY
content:
<i><b>cookiecutter</b></i> was created by Audrey Roy Greenfeld and Daniel Greenfeld, with its initial release dating back to 2013. It rapidly gained traction, especially within the Python development community, as a de-facto standard for standardizing project layouts and boilerplate code generation. Its ease of use and flexibility contributed significantly to its widespread adoption, helping developers maintain consistency and accelerate new project creation workflows across various programming ecosystems.


title: SYNOPSIS
content:
<br><b>copr</b> [<i>GLOBAL_OPTIONS</i>] <i>COMMAND</i> [<i>COMMAND_OPTIONS</i>] [<i>ARGUMENTS</i>]<br><br>Examples:<br><br><b>copr</b> <b>build</b> <i>project_name</i> <i>SRPM_file.src.rpm</i><br><br><b>copr</b> <b>list</b> <b>--my-projects</b><br><br><b>copr</b> <b>repo</b> <b>enable</b> <i>project_name</i>


title: PARAMETERS
content:
<b><b>--config</b> <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a custom configuration file path instead of the default.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the <b>copr</b> client.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows a help message for the <b>copr</b> command or a specific subcommand if provided.<br><br>


title: DESCRIPTION
content:
The <b>copr</b> command (typically executed as <b>copr-cli</b>) is the command-line client for interacting with the <I>COPR</I> (Community PRojects) build system. COPR is a free and open-source automated build service primarily used by Fedora, CentOS, and Red Hat Enterprise Linux users to build and host custom RPM repositories. It allows developers and users to build software packages outside of the official distribution repositories. <br><br>The <b>copr</b> client enables users to manage their COPR projects, initiate new builds, monitor build status, manage repositories, and perform user-related actions directly from their terminal. This includes creating new projects, uploading SRPMs (Source RPMs) for building, enabling COPR repositories on their systems for easy installation of built packages, and listing existing projects or builds. It streamlines the process of distributing software that isn't yet, or will never be, part of official distribution channels.


title: CAVEATS
content:
Requires an active internet connection to communicate with the COPR service.<br>Requires a COPR account for most operations like building or managing projects.<br>Primarily focused on RPM-based Linux distributions (Fedora, CentOS, RHEL).<br>Building untrusted SRPMs can pose security risks, as builds execute in a controlled environment but might consume resources or exploit vulnerabilities if not properly reviewed.


title: <BR><B>SUBCOMMANDS OVERVIEW</B><BR>
content:
The <b>copr</b> command operates using a subcommand structure. Common subcommands include: <br><b>build</b> (to initiate package builds), <br><b>create</b> (to set up new projects or objects), <br><b>list</b> (to view existing projects, builds, or repositories), <br><b>delete</b> (to remove projects or builds), <br><b>enable</b> (to enable COPR repositories on your system), <br><b>login</b>/<b>logout</b> (for authentication), <br><b>monitor</b> (to track build progress), and <br><b>repo</b> (to manage repository-specific actions). Each subcommand often has its own set of options and arguments.


title: <BR><B>INSTALLATION</B><BR>
content:
The <b>copr-cli</b> client is typically installed via the system's package manager on Fedora-based distributions. For example: <br><i>sudo dnf install copr-cli</i><br>Once installed, it can be invoked as <b>copr</b> or <b>copr-cli</b> depending on the specific environment and PATH configuration.


title: HISTORY
content:
The COPR build system originated as a community project within Fedora, aiming to provide a flexible and easy-to-use platform for building and distributing software packages outside of the official Fedora repositories. It has evolved significantly since its inception, becoming an integral part of the Fedora ecosystem for testing new software, hosting personal projects, and enabling third-party software distribution. The <b>copr-cli</b> client was developed to provide a robust command-line interface for seamless interaction with the COPR service, reflecting the system's focus on automation and developer workflows.


title: SYNOPSIS
content:
<b>copr-cli</b> [<i>GLOBAL_OPTIONS</i>] <i>&lt;command&gt;</i> [<i>COMMAND_OPTIONS</i>] [<i>ARGUMENTS</i>]


title: PARAMETERS
content:
<b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a help message and exit for the main command or a specific subcommand.<br><br><b>--config-file <i>CONFIG_FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative path to the configuration file (default: <i>/etc/copr/copr-cli.conf</i>, <i>~/.config/copr/copr-cli.conf</i>).<br><br><b>--no-config-file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent <b>copr-cli</b> from using any configuration files.<br><br><b>--result-url</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When applicable, show a URL to the build result or other resource.<br><br><b>--api-url <i>API_URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the URL of the Copr API endpoint to connect to.<br><br><b>--auth-url <i>AUTH_URL</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the URL of the Copr Authentication server.<br><br><b>--token <i>TOKEN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide an authentication token directly. This overrides any token found in configuration files.<br><br><b>--login <i>LOGIN</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Log in to the Copr service, typically used to obtain a new authentication token.<br><br><b>--proxy <i>PROXY</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a specified HTTP/HTTPS proxy for all network requests.<br><br><b>--no-ssl-verify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable SSL certificate verification. Use with caution, as it can expose you to security risks.<br><br><b>--ca-file <i>CA_FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom CA certificate file for SSL verification.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output, providing more detailed information for troubleshooting.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more information about operations.<br><br>


title: DESCRIPTION
content:
The <b>copr-cli</b> command is a powerful command-line interface tool designed to interact with the Copr build system. Copr is a Fedora infrastructure service that provides a public build service for RPM-based Linux distributions, including Fedora, RHEL, CentOS Stream, and EPEL. <br><br><b>copr-cli</b> allows users to manage their Copr projects and builds directly from the terminal, bypassing the need for the web interface. It enables tasks such as creating new projects, submitting new package builds (from SRPMs, Git repositories, or existing dist-git repos), monitoring build statuses, managing project permissions, and listing existing projects or builds. This utility is particularly useful for developers, packagers, and maintainers who frequently build and test software, providing an efficient way to integrate Copr into their automated workflows and CI/CD pipelines.


title: CAVEATS
content:
Successful interaction with the Copr service typically requires an active internet connection and a valid Copr account with appropriate permissions. For most operations, an API token or a successful login is mandatory. Be cautious when using <i>--no-ssl-verify</i> as it compromises security. The functionality of <b>copr-cli</b> is tightly coupled with the Copr API, meaning changes to the API might require updates to the client.


title: SUBCOMMANDS
content:
<b>copr-cli</b> operates using a subcommand-based architecture. After the global options, you must specify a command that defines the action to be performed. Each subcommand has its own set of specific options and arguments. Common subcommands include: <br><b>build</b>: Manage package builds (e.g., submit, monitor, cancel).<br><b>create</b>: Create and manage Copr projects.<br><b>delete</b>: Remove Copr projects, builds, or other resources.<br><b>list</b>: List various Copr resources (projects, builds, repositories).<br><b>monitor</b>: Continuously track the status of builds.<br><b>permissions</b>: Manage user permissions for a project.<br><b>repo</b>: Manage project repositories.<br><b>update</b>: Modify existing projects.<br>To see options for a specific subcommand, use <b>copr-cli</b> <i>&lt;command&gt;</i> <b>--help</b> (e.g., <b>copr-cli build --help</b>).


title: AUTHENTICATION
content:
To interact with the Copr service, you typically need to authenticate. This is most commonly done by obtaining an API token from the Copr web interface and storing it in your configuration file or providing it via the <i>--token</i> option. The <i>--login</i> option can also be used to facilitate interactive authentication.


title: HISTORY
content:
The Copr build system was initiated as a Fedora project to provide flexible and accessible build services for RPM packages. As the service grew in popularity and functionality, the need for a robust command-line interface became apparent. <b>copr-cli</b> was developed as the official client, providing a programmatic way to interact with the Copr API. Its development has mirrored the evolution of the Copr service itself, with new features and commands being added to support expanded capabilities like enhanced build management, project permissions, and different source input types. It has become an indispensable tool for Fedora contributors, independent packagers, and anyone looking to distribute RPMs efficiently.


title: PARAMETERS
content:
<b><I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. An array name where the file descriptors for the coprocess's pipes will be stored. If omitted, the default array name <i>COPROC</i> is used. <i>NAME[0]</i> holds the file descriptor for writing to the coprocess's standard input, and <i>NAME[1]</i> holds the file descriptor for reading from the coprocess's standard output.<br><br><b><I>command</I> [<I>arguments</I>...]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The command and its arguments to be executed as the coprocess. This command runs in a separate subshell process.<br><br>


title: DESCRIPTION
content:
The <b>coproc</b> keyword in Bash (Bourne-Again SHell) provides a powerful mechanism for running commands asynchronously as "coprocesses," establishing a direct, bidirectional communication channel between the parent shell and the child process. <br><br>When invoked, <b>coproc</b> launches the specified <i>command</i> in a subshell, executing it in the background. Simultaneously, it creates two pipes: one for sending data to the coprocess's standard input, and another for receiving data from its standard output. The file descriptors (FDs) for these pipes are stored in a shell array. By default, this array is named <i>COPROC</i>, but a custom <i>NAME</i> can be provided. Specifically, <i>NAME[0]</i> (or <i>COPROC[0]</i>) holds the FD to which the parent shell writes data, which becomes the coprocess's standard input. Conversely, <i>NAME[1]</i> (or <i>COPROC[1]</i>) holds the FD from which the parent shell reads data, which originates from the coprocess's standard output. <br><br>This setup facilitates sophisticated inter-process communication (IPC) directly within a shell script. It allows the parent script to feed input to a long-running background process and consume its output dynamically, enabling shell-based client-server patterns or asynchronous task management. Unlike simple backgrounding with '&amp;', <b>coproc</b> specifically establishes the I/O pipes, making interactive communication straightforward. It is particularly useful for scripting scenarios where real-time interaction with a background service or data processing pipeline is required.


title: CAVEATS
content:
<b>Bash Specific</b>: <b>coproc</b> is a Bash shell built-in keyword, not a standard POSIX command. It will not work in other shells like <i>sh</i>, <i>dash</i>, or <i>zsh</i> (without Bash emulation).<br><br><b>File Descriptor Management</b>: It's crucial to correctly manage the file descriptors. Unclosed descriptors can lead to resource leaks or unexpected behavior. Closing the write FD (e.g., <i>COPROC[0]</i>) is often necessary to signal EOF to the coprocess.<br><br><b>Error Handling</b>: <b>coproc</b> itself doesn't provide robust error handling for the coprocess's failures. The shell must explicitly check the coprocess's exit status (e.g., using <i>wait</i>) and handle its <i>stderr</i> if needed (by redirecting it within the coproc command).<br><br><b>Debugging Challenges</b>: Debugging I/O issues and race conditions with pipes can be challenging.


title: INTERACTING WITH THE COPROCESS
content:
To send input to the coprocess's standard input: <b>echo</b> "<i>data</i>" <b>&gt;&amp;</b> ${<i>COPROC</i>[0]}<br><br>To read output from the coprocess's standard output: <b>read</b> -u ${<i>COPROC</i>[1]} <i>variable</i><br><br>It is often necessary to close the write end of the pipe (e.g., <b>exec</b> ${<i>COPROC</i>[0]}<b>&lt;&amp;-</b>) after sending all input to signal EOF to the coprocess, allowing it to complete its processing.


title: JOB CONTROL AND PIDS
content:
The coprocess runs as a background job. Its job ID and PID can be accessed via <b>COPROC_PID</b> (or <i>NAME_PID</i> if a custom <i>NAME</i> was used). Its job number can be seen with <b>jobs</b>. The parent shell can use <b>wait</b> to await its termination, <b>kill</b> to send signals, or <b>disown</b> to remove it from the job table.


title: FILE DESCRIPTOR BEHAVIOR
content:
By default, <b>coproc</b> sets the coprocess's standard input to <i>/dev/null</i>. Standard output and standard error are inherited from the parent shell, but the coprocess's standard output is also connected to the read pipe (<i>COPROC[1]</i>). If standard error needs to be captured via the pipe, it must be explicitly redirected to standard output within the <b>coproc</b> command (e.g., <b>coproc</b> <i>command</i> <b>2&gt;&amp;1</b>).


title: HISTORY
content:
<b>coproc</b> was introduced in <b>Bash 4.0</b> (released February 2009). Its addition aimed to provide a more convenient and robust way to manage asynchronous processes with direct bidirectional I/O channels from within Bash scripts, without needing to rely on external utilities like <i>mkfifo</i> or complex <i>exec</i> redirections and process substitutions. It streamlined inter-process communication for shell scripts.


title: SYNOPSIS
content:
copyq [<I>options</I>] [<I>command</I> [<I>arguments</I>]]<br><br>Examples:<br><i>copyq show</i><br><i>copyq read 0</i><br><i>copyq write "Hello World"</i><br><i>copyq paste</i>


title: PARAMETERS
content:
<b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information about the command-line usage.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the version of CopyQ.<br><br><b>--start-server</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the CopyQ daemon (background process) if it's not already running.<br><br><b>--stop-server</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops the running CopyQ daemon.<br><br><b>--toggle</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Toggles the visibility of the main CopyQ window.<br><br><b>--show</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the main CopyQ window.<br><br><b>--hide</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Hides the main CopyQ window.<br><br><b>--menu</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the context menu at the current mouse cursor position.<br><br><b>--paste [index]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pastes the item at the specified <i>index</i> (default 0, the latest) to the currently active application.<br><br><b>--selection [index]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies the item at the specified <i>index</i> to the primary selection (X11).<br><br><b>--history</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the history tab in the main window.<br><br><b>--read [index]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the content of the item at <i>index</i> (default 0) to standard output.<br><br><b>--write [text]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the specified <i>text</i> to the clipboard. Use <i>-</i> to read from stdin.<br><br><b>--remove [index]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the item at the specified <i>index</i> (default 0) from history.<br><br><b>--eval [script]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the given JavaScript <i>script</i> within the CopyQ environment.<br><br><b>--print [item_format]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints specific data of the item at index 0 (e.g., 'text', 'image', 'html', 'all').<br><br><b>--config [key] [value]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads or sets a configuration <i>key</i>. If <i>value</i> is omitted, prints the current setting.<br><br><b>--tabs</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available tab names.<br><br><b>--insert [tab_name] [index]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inserts a new tab with the specified <i>tab_name</i> at the given <i>index</i>.<br><br><b>--move [index] [new_index]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Moves an item from its current <i>index</i> to a <i>new_index</i> within the history.<br><br>


title: DESCRIPTION
content:
<b>CopyQ</b> is a powerful, cross-platform clipboard manager with advanced features. It monitors the system clipboard and stores a history of all copied content, including text, images, HTML, and other data types. Users can easily browse, search, and manage this history through a customizable graphical interface or a comprehensive command-line interface.<br><br>Key functionalities include pasting previously copied items, editing clipboard contents, executing custom actions, and scripting for automation. <b>CopyQ</b> aims to enhance productivity by providing robust clipboard management capabilities beyond typical system clipboard functionality, allowing users to quickly access, manipulate, and reuse past clipboard entries.


title: CAVEATS
content:
<b>CopyQ</b> relies on a background server process to function. Command-line operations will fail if the server is not running. On some Linux distributions or with containerized applications (e.g., Snap, Flatpak), direct clipboard access or interaction might be restricted due to security sandboxing, requiring specific permissions or workarounds. As a Qt-based GUI application, it has GUI library dependencies.


title: SERVER-CLIENT ARCHITECTURE
content:
<b>CopyQ</b> operates with a server-client model. The main <b>CopyQ</b> application runs as a server daemon in the background, continuously monitoring the clipboard. All command-line interactions act as clients communicating with this running server, allowing for seamless integration into scripts and workflows without needing to open the GUI manually.


title: CUSTOMIZATION AND SCRIPTING
content:
One of <b>CopyQ</b>'s most powerful features is its extensive customization options. Users can create custom actions triggered by specific clipboard content, define keyboard shortcuts, and leverage a built-in JavaScript engine for advanced scripting. This allows for automation of complex tasks, such as automatically converting text formats, running external commands, or filtering content upon copy.


title: RICH DATA TYPE SUPPORT
content:
Unlike simple clipboard tools, <b>CopyQ</b> can handle and store various data types beyond plain text. This includes images, HTML, rich text format (RTF), and custom MIME types. This capability is crucial for users who frequently copy complex content from web browsers, document editors, or image applications, ensuring that formatting and non-textual data are preserved in the history.


title: HISTORY
content:
Developed by Lukas Sabat, <b>CopyQ</b> emerged as a versatile clipboard manager, initially targeting X11 environments but quickly expanding its reach to become a cross-platform solution for Linux, Windows, and macOS. Its development has focused on robust functionality, extensibility through scripting, and a user-friendly interface, making it a popular choice for power users seeking enhanced clipboard capabilities.


title: SYNOPSIS
content:
<b>cordova</b> <i>&lt;command&gt;</i> [<i>options</i>]<br><b>cordova</b> <i>&lt;command&gt;</i> <b>--help</b><br><br><u>Common commands:</u><br><b>cordova create</b> <i>&lt;path&gt;</i> [<i>id</i>] [<i>name</i>]<br><b>cordova platform add</b> <i>&lt;platform_name&gt;</i><br><b>cordova build</b> [<i>platform_name</i>] [<i>--release</i>|<i>--debug</i>]<br><b>cordova emulate</b> <i>&lt;platform_name&gt;</i><br><b>cordova run</b> <i>&lt;platform_name&gt;</i><br><b>cordova plugin add</b> <i>&lt;plugin_id&gt;</i>


title: PARAMETERS
content:
<b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the installed Cordova CLI version number.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays general help or detailed help for a specific command.<br><br><b><b>create</b> <i>&lt;path&gt;</i> [<i>id</i>] [<i>name</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a new Cordova project in the specified directory.<br><b><i>&lt;path&gt;</i></b>: <i>Required.</i> The target directory for the new project.<br><b>[<i>id</i>]</b>: <i>Optional.</i> A reverse-domain-style identifier for the application (e.g., <i>com.example.myapp</i>).<br><b>[<i>name</i>]</b>: <i>Optional.</i> The human-readable display name for the application.<br><br><b><b>platform add|rm</b> <i>&lt;platform_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds or removes a target mobile platform to or from your project.<br><b><i>&lt;platform_name&gt;</i></b>: <i>Required.</i> The name of the platform (e.g., <i>android</i>, <i>ios</i>, <i>browser</i>).<br><br><b><b>build|run|emulate</b> [<i>platform_name</i>] [<i>--release</i>|<i>--debug</i>|<i>--device</i>|<i>--emulator</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Builds, runs, or emulates the application on a specific or all added platforms.<br><b>[<i>platform_name</i>]</b>: <i>Optional.</i> Specifies a particular platform to target; if omitted, all added platforms are targeted.<br><b><i>--release</i></b>: <i>Optional.</i> Builds the application for release (signed and optimized).<br><b><i>--debug</i></b>: <i>Optional.</i> Builds the application for debugging (unsigned and debuggable).<br><b><i>--device</i></b>: <i>Optional.</i> Deploys the application to a connected physical device.<br><b><i>--emulator</i></b>: <i>Optional.</i> Deploys the application to an emulator or simulator.<br><br><b><b>plugin add|rm</b> <i>&lt;plugin_id&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds or removes a plugin to or from the project.<br><b><i>&lt;plugin_id&gt;</i></b>: <i>Required.</i> The identifier of the plugin (e.g., <i>cordova-plugin-camera</i>), a local path, or a Git URL.<br><br>


title: DESCRIPTION
content:
The <b>cordova</b> command-line interface (CLI) is a powerful tool for <i>Apache Cordova</i>, an open-source framework that enables developers to build hybrid mobile applications using standard web technologies like HTML, CSS, and JavaScript. It provides a comprehensive set of commands to create, configure, build, run, and manage Cordova projects.<br><br>The CLI acts as a crucial bridge, allowing web assets (your application's code) to be packaged into native application wrappers for various mobile operating systems, such as <i>Android</i>, <i>iOS</i>, and <i>Windows</i>. This capability allows developers to write their application code once and deploy it across multiple platforms, significantly reducing development time and effort compared to building fully native applications for each platform individually. Beyond core project management, the <b>cordova</b> command facilitates the integration of native device functionalities through plugins and manages platform-specific builds and emulations.


title: CAVEATS
content:
The <b>cordova</b> command itself requires <b>Node.js</b> and <b>npm</b> (Node Package Manager) to be installed and configured on the system. Furthermore, building and running applications for specific mobile platforms (e.g., <i>Android</i>, <i>iOS</i>) necessitates additional platform-specific SDKs and tools (e.g., <i>Android SDK</i>, <i>Xcode</i> for <i>iOS</i>) to be properly installed and their environment variables (like <i>ANDROID_HOME</i>) configured. Development for <i>iOS</i> is generally restricted to <i>macOS</i> environments due to Apple's licensing and tooling requirements. Hybrid applications may exhibit performance limitations compared to fully native apps, particularly in graphics-intensive scenarios. Debugging can also be more complex due to the layered nature of hybrid development.


title: PLUGINS
content:
Cordova's core functionality is extended through <i>plugins</i>. Plugins provide JavaScript APIs that allow your web application to access native device capabilities like the camera, GPS, contacts, accelerometer, and file system, which are not directly accessible from standard web views. Developers can utilize official <i>Apache</i> plugins, community-contributed plugins, or even develop their own custom plugins to integrate specific native features.


title: PLATFORMS
content:
While Cordova abstracts away much of the platform-specific code, projects still target individual mobile platforms. The <b>cordova</b> CLI manages the platform-specific project structure within your main Cordova project directory. Each platform (e.g., <i>Android</i>, <i>iOS</i>, <i>Browser</i>) maintains its own native project files, which the CLI generates and updates based on your web assets and configuration.


title: HOOKS
content:
The <b>cordova</b> CLI supports <i>hooks</i>, which are custom scripts that can be executed automatically before or after specific Cordova commands (e.g., <i>before_build</i>, <i>after_prepare</i>, <i>before_plugin_add</i>). Hooks provide a powerful mechanism for automating custom tasks, such as modifying configuration files, running tests, or performing code transformations, throughout the development and build workflow.


title: HISTORY
content:
Apache Cordova originated as <i>PhoneGap</i>, an innovative open-source framework developed by <i>Nitobi</i>. In 2011, <i>Adobe</i> acquired <i>Nitobi</i> and subsequently open-sourced <i>PhoneGap's</i> core, contributing it to the <i>Apache Software Foundation</i> under the name <i>Apache Cordova</i>. <i>Adobe</i> continues to offer its commercial version under the <i>PhoneGap</i> brand, while the open-source project is maintained by the <i>Apache Cordova</i> community. This pivotal move democratized cross-platform mobile development using ubiquitous web technologies, enabling developers to target multiple mobile operating systems without the need to learn platform-specific languages like <i>Java/Kotlin</i> for <i>Android</i> or <i>Objective-C/Swift</i> for <i>iOS</i>. Its ongoing development has focused on enhancing performance, expanding plugin capabilities, and adapting to the evolving features and requirements of mobile operating systems.


title: SYNOPSIS
content:
<I>Typically invoked by Git hooks or CI systems</I><br><b>core-validate-commit</b> [<i>options</i>] [<i>commit-range</i>]


title: PARAMETERS
content:
<b>[<i>commit-range</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a commit hash or a range of commits to validate (e.g., <I>HEAD</I>, <I>HEAD~3..HEAD</I>). If omitted, it often validates the current commit being staged or pushed.<br><br><b><b>-v</b>, <b>--verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing more details about the checks being performed and their results.<br><br><b><b>-n</b>, <b>--dry-run</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Perform checks without taking any action or enforcing failure, useful for testing the script's behavior.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit.<br><br><b><b>--strict</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enforce stricter validation rules, potentially failing on warnings that would otherwise be ignored.<br><br>


title: DESCRIPTION
content:
The <b>core-validate-commit</b> is not a standard, globally available Linux command, but rather a generic name for a <i>script</i> often used in large-scale software development projects to enforce specific Git commit message and formatting guidelines.<br><br>Typically, this script is part of a project's repository and is invoked as a <B>Git hook</B> (e.g., <I>pre-commit</I> or <I>commit-msg</I>) or within a <B>Continuous Integration/Continuous Deployment (CI/CD)</B> pipeline. Its primary purpose is to ensure that all commits adhere to predefined project standards, which can include checks on commit message length, subject line format, presence of sign-off lines (e.g., <I>Signed-off-by:</I>), proper author and committer email formats, inclusion of bug IDs, or adherence to specific commit message templates.<br><br>By automating these checks, <b>core-validate-commit</b> helps maintain a clean, consistent, and easily traceable project history, improving readability, simplifying future code reviews, and streamlining automated processing of commit messages (e.g., for changelog generation or issue tracking integration). Its exact implementation and the rules it enforces are highly customizable and specific to each project's needs.


title: CAVEATS
content:
<b>core-validate-commit</b> is not a standard Linux command; its availability and functionality are entirely dependent on specific project implementations. There is no universal manual page, and its behavior, parameters, and rules can vary significantly between different repositories or development teams. Users should consult the specific project's documentation or the script itself for precise details.


title: COMMON CHECKS PERFORMED
content:
While implementation-dependent, a typical <b>core-validate-commit</b> script might perform checks such as:<br><i>* Subject Line Format:</i> Length limits (e.g., 50 characters), capitalization, no trailing punctuation.<br><i>* Body Format:</i> Wrapping at 72-75 characters, separation from subject line, absence of tabs.<br><i>* Sign-off By:</i> Presence and correct format of <I>Signed-off-by:</I> lines, often verifying email addresses.<br><i>* Author/Committer:</i> Verification of valid email addresses and names.<br><i>* Change-ID/Bug-ID:</i> Requirement for specific IDs (e.g., for Gerrit, JIRA) in the commit message.<br><i>* DCO (Developer Certificate of Origin):</i> Ensuring DCO compliance.<br><i>* Code Style:</i> Sometimes, it might integrate with basic code style checks on the committed changes.<br>


title: INTEGRATION METHODS
content:
<b>core-validate-commit</b> is primarily integrated in two ways:<br><i>* Git Hooks:</i> Often installed as a <I>commit-msg</I> hook to validate the commit message before the commit is finalized, or as a <I>pre-push</I> hook to validate commits before they are pushed to a remote repository.<br><i>* CI/CD Pipelines:</i> Executed as part of a Continuous Integration job (e.g., Jenkins, GitHub Actions, GitLab CI/CD) to validate incoming merge requests or pushed commits against project standards, providing immediate feedback to developers.<br>


title: HISTORY
content:
The concept behind <b>core-validate-commit</b> emerged from the need for stringent commit hygiene in large, collaborative open-source projects, particularly those with complex contribution guidelines like the Linux kernel. While no single 'history' exists for this specific command name (as it's often a custom script), the practice of using automated commit validation scripts became widespread in the early 2010s. This was driven by the desire to reduce manual review effort, ensure consistent historical records, and facilitate automated tools that parse commit messages. Projects began developing their own internal scripts, and `core-validate-commit` or similar names (e.g., `checkpatch.pl` in Linux kernel, but `core-validate-commit` is distinct) became common patterns for validating commit messages, authorship, and sign-offs, especially in vendor-specific kernel trees or large enterprise codebases.


title: PARAMETERS
content:
<b><i>COMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The specific operation to perform. Common commands include <b>list</b> (to list dumps), <b>info</b> (to show details), <b>dump</b> (to extract raw dump), <b>gdb</b> (to launch debugger), <b>extract</b> (to extract files), and <b>cat</b> (to show stdout/stderr).<br><br><b><i>PID</i>|<i>COMMISSION</i>|<i>PATH</i>...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more identifiers for core dumps. Can be a process ID (PID), an executable name (COMMISSION), or a file path to a core dump.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output in JSON format, useful for scripting and programmatic parsing.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show core dumps from all users and sessions, not just the current one.<br><br><b>--no-pager</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not pipe output into a pager program (e.g., less), displaying it directly to the console.<br><br><b>--unit=<I>UNIT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filter core dumps by the systemd unit name that generated them (e.g., --unit=my-service.service).<br><br><b>--output=<I>FIELD</I>,...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a comma-separated list of fields to display for the <b>list</b> command. Available fields can be found in the manual.<br><br><b>--field=<I>FIELD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add an extra field to the default output of the <b>list</b> command without replacing defaults.<br><br><b>--since=<I>DATE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show core dumps since a specified date or time string (e.g., '2023-01-01', 'yesterday', 'now - 1h').<br><br><b>--until=<I>DATE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show core dumps until a specified date or time string.<br><br><b>--file=<I>FILE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an uncompressed core dump file to operate on instead of querying the systemd journal/storage directly.<br><br><b>--executable=<I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the path to the original executable that corresponds to the core dump for some operations like <b>gdb</b> or <b>debug</b>.<br><br>


title: DESCRIPTION
content:
<i>coredumpctl</i> is a command-line utility used to query, inspect, and extract core dumps collected by the <i>systemd-coredump</i> service. It provides a standardized and integrated way to handle process crashes on Linux systems running <i>systemd</i>.<br><br>When an application crashes, the kernel typically generates a core dump file containing a snapshot of the process's memory and state. The <i>systemd-coredump</i> service, acting as a kernel helper, captures these dumps, compresses them (often using <i>zstd</i>), and stores them in a designated location (usually /var/lib/systemd/coredump).<br><br><i>coredumpctl</i> allows administrators and developers to list available core dumps, view their metadata, extract the original executable or other relevant files, and even directly launch a debugger like <i>gdb</i> on a specific core dump, significantly simplifying debugging efforts.


title: CAVEATS
content:
<b>Core Dump Storage:</b> Core dumps can be very large, potentially consuming significant disk space. Ensure sufficient storage and consider <i>systemd-coredump</i> configuration for cleanup policies.<br><b>Sensitive Information:</b> Core dumps contain a snapshot of a process's memory, which may include sensitive data like passwords, encryption keys, or private user information. Exercise caution when sharing or storing them.<br><b>Permissions:</b> Accessing core dumps, especially those from other users or system processes, typically requires elevated privileges (e.g., root access) or membership in the <i>systemd-coredump</i> group.


title: CORE DUMP STORAGE LOCATION
content:
By default, <i>systemd-coredump</i> stores processed core dumps in a dedicated location, usually <i>/var/lib/systemd/coredump</i>. These files are often compressed (e.g., with <i>zstd</i>) to save disk space.


title: INTEGRATION WITH SYSTEMD-JOURNALD
content:
Metadata about each core dump (e.g., crashing PID, executable path, signal) is logged to the <i>systemd journal</i>. <i>coredumpctl</i> queries this journal for filtering and listing core dumps. The actual core dump data is stored separately from the journal.


title: COMPRESSION
content:
Core dumps are typically compressed by <i>systemd-coredump</i> using <i>zstd</i> for efficient storage. <i>coredumpctl</i> can decompress them on the fly when you use commands like <b>gdb</b>, <b>dump</b>, or <b>extract</b>, or you can explicitly uncompress them using the <b>uncompress</b> command.


title: HISTORY
content:
Part of the <i>systemd</i> project, <i>coredumpctl</i> was introduced to provide a standardized, integrated mechanism for handling process core dumps. Its development aimed to replace ad-hoc core dump collection scripts and enable system-wide management and inspection of crash artifacts directly within the <i>systemd</i> ecosystem. It leverages the kernel's <i>core_pattern</i> mechanism, redirecting core dumps to the <i>systemd-coredump</i> service for processing and storage.


title: SYNOPSIS
content:
<i><b>N/A</b></i> - Not a standard Linux command. Its syntax, if it exists, would be custom to its implementation.


title: PARAMETERS
content:
<b><i><b>N/A</b></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;As <i><b>corelist</b></i> is not a standard Linux command, there are no universally defined parameters or options. Any parameters would be specific to a custom implementation if one exists.<br><br>


title: DESCRIPTION
content:
The command <i><b>corelist</b></i> is not a standard, widely recognized, or pre-installed utility found in most mainstream Linux distributions (e.g., Debian, Ubuntu, CentOS, Fedora, Arch Linux).<br><br>This suggests that <i><b>corelist</b></i> might be one of the following:<br><i><b><br>- A custom shell script created for a specific environment or purpose.<br>- A component or internal function within a larger application or framework, not intended for direct command-line execution as a standalone utility.<br>- A typo for a similar-sounding command.<br>- A command unique to a very specific, niche distribution or legacy system.</b></i><br><br>Because it is not a standard command, there is no universal manual page (e.b. <i><b>man corelist</b></i> e.g.) or predefined behavior, options, or typical usage patterns that can be documented generically. Its functionality, if it exists on a particular system, would be entirely dependent on its specific implementation on that system.


title: CAVEATS
content:
The non-standard nature of <i><b>corelist</b></i> means its presence, behavior, and security implications (if any) are entirely dependent on its source. Users should exercise caution if they encounter this command and verify its origin and purpose before execution. It will likely not be available on typical Linux installations.


title: HOW TO INVESTIGATE A CUSTOM <I><B>CORELIST</B></I> COMMAND
content:
If you encounter <i><b>corelist</b></i> on a specific system and wish to understand its function, you might try the following steps:<br><i><b><br>- Use <i><b>which corelist</b></i> to locate its executable path.<br>- If found, examine the file's contents (e.g., using <i><b>cat /path/to/corelist</b></i> or <i><b>less /path/to/corelist</b></i>) to see if it's a shell script.<br>- Check system logs or documentation specific to your environment for mentions of this command.<br>- Consult with system administrators or developers familiar with the specific system where <i><b>corelist</b></i> is present.</b></i>


title: HISTORY
content:
<i><b>N/A</b></i> - There is no general development history for <i><b>corelist</b></i> as a standard Linux command. Its 'history' would be tied to its specific creation and usage within a particular system or project.


title: SYNOPSIS
content:
<b>corepack</b> <i>&lt;command&gt;</i> [<i>arguments...</i>]<br><b>corepack</b> <i>--version</i> | <i>-v</i><br><b>corepack</b> <i>--help</i>


title: PARAMETERS
content:
<b><b>enable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates <i>Corepack</i>. This installs shims (proxy executables) for <i>npm</i>, <i>yarn</i>, and <i>pnpm</i> in a location found by your PATH, allowing <i>Corepack</i> to intercept calls to these package managers.<br><br><b><b>disable</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deactivates <i>Corepack</i>. This removes the shims, restoring direct calls to globally installed package managers (or those bundled with Node.js).<br><br><b><b>prepare</b> <i>&lt;binary-path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An internal command primarily used by Node.js distributions to prepare <i>Corepack</i> shims. Not typically used by end-users directly.<br><br><b><b>install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An internal command used to install package managers managed by <i>Corepack</i> into its cache. Not typically used directly by end-users.<br><br><b><i>--version</i> | <i>-v</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <i>Corepack</i> version number.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for <i>Corepack</i>.<br><br>


title: DESCRIPTION
content:
<i>Corepack</i> is an experimental Node.js tool designed to manage which package manager is used for a given project. It ensures that all team members and CI/CD environments use the exact same version of <i>npm</i>, <i>Yarn</i>, or <i>pnpm</i> defined by the project's <code>packageManager</code> field in its <code>package.json</code> file. <br><br>When enabled, <i>Corepack</i> intercepts calls to <code>npm</code>, <code>yarn</code>, or <code>pnpm</code> and, if a <code>packageManager</code> field is present in the project's <code>package.json</code>, it transparently downloads and uses the specified package manager version. This eliminates the need for developers to manually install or switch between different package manager versions, greatly improving project consistency and reproducibility across various development environments. It's bundled with Node.js since version 16.9.0 but often requires explicit activation.


title: CAVEATS
content:
<ul><li><i>Corepack</i> is bundled with Node.js 16.9.0 and newer, but is often disabled by default in many distributions (e.g., Node.js installed via OS package managers or <i>nvm</i>). It must be explicitly enabled using <code>corepack enable</code>.</li><li>It relies on the <code>packageManager</code> field in <code>package.json</code>. Projects without this field will fallback to globally installed or Node.js bundled package managers.</li><li><i>Corepack</i> primarily manages <i>Yarn</i> and <i>pnpm</i> versions. For <i>npm</i>, it manages its version only if the <code>packageManager</code> field specifies an <i>npm</i> version different from the one bundled with Node.js.</li><li>Enabling <i>Corepack</i> creates shims that might override globally installed versions of <i>yarn</i> or <i>pnpm</i>, which can sometimes lead to unexpected behavior if not understood.</li></ul>


title: TRANSPARENT PROXYING
content:
Once <i>Corepack</i> is enabled and shims are in place, invoking <code>yarn</code> or <code>pnpm</code> (or <code>npm</code>, if specified in <code>packageManager</code>) from your project's root directory will automatically delegate to <i>Corepack</i>. <i>Corepack</i> then reads the <code>packageManager</code> field in <code>package.json</code> (e.g., <code>"packageManager": "yarn@3.2.0"</code>) and ensures that the correct version of the package manager is downloaded (if not cached) and used for the current command.


title: <CODE>PACKAGEMANAGER</CODE> FIELD
content:
The <code>packageManager</code> field in <code>package.json</code> is crucial for <i>Corepack</i>'s operation. It specifies the package manager and its exact version that a project expects. For example:<br><code>{ "name": "my-project", "version": "1.0.0", "packageManager": "yarn@3.2.0" }</code><br>or<br><code>{ "name": "my-project", "version": "1.0.0", "packageManager": "pnpm@7.1.0" }</code><br>This field acts as the single source of truth for the package manager version within the project.


title: HISTORY
content:
<i>Corepack</i> was introduced as an experimental feature with <i>Node.js</i> <b>v16.9.0</b>. Its development was driven by the increasing need for consistent package manager versions across projects, similar to how tools like <i>nvm</i> or <i>volta</i> manage Node.js versions. By bundling it directly into <i>Node.js</i>, the aim was to provide a standardized, cross-platform solution to address the 'works on my machine' problem that arises when different team members use different package manager versions. It became stable and enabled by default in <i>Node.js</i> <b>v19.0.0</b>, though older Node.js versions might still require explicit enabling.


title: SYNOPSIS
content:
<I>Coreutils is a package, not a single command with a direct synopsis.</I><br>It comprises hundreds of individual commands, each with its own specific syntax and options.<br>For example, a typical command from the coreutils suite, such as <b>ls</b>, would have a synopsis like:<br><b><I>ls [OPTION]... [FILE]...</I></b><br>Each utility within the coreutils package follows the standard Unix command line syntax for options and arguments.


title: PARAMETERS
content:
<b><I>Not applicable to the coreutils package itself.</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>coreutils</b> package itself does not accept parameters.<br>Instead, each of the individual utilities contained within the <b>coreutils</b> suite has its own set of parameters and options.<br>For instance, the <b>ls</b> command has parameters such as <b>-l</b> (long listing format), <b>-a</b> (do not ignore entries starting with .), and <b>-h</b> (with -l, print human readable sizes). The <b>cp</b> command has <b>-r</b> (recursive copy), <b>-i</b> (interactive, prompt before overwrite), etc. Users should consult the manual page (e.g., <I>man &lt;command_name&gt;</I>) for the specific parameters of any individual <b>coreutils</b> command.<br><br>


title: DESCRIPTION
content:
coreutils is not a single executable command, but rather a fundamental package containing the essential GNU command-line utilities. These utilities provide the basic building blocks for interacting with the file system, manipulating text, and managing processes in Unix-like operating systems, including Linux. They are indispensable for scripting and everyday system administration. The package comprises three main groups of utilities: file utilities (e.g., <b>ls</b>, <b>cp</b>, <b>mv</b>, <b>rm</b>, <b>mkdir</b>, <b>chmod</b>), text utilities (e.g., <b>cat</b>, <b>sort</b>, <b>uniq</b>, <b>wc</b>, <b>head</b>, <b>tail</b>), and shell utilities (e.g., <b>true</b>, <b>false</b>, <b>echo</b>, <b>printf</b>). Almost every interaction with a Linux system, from simple directory listing to complex scripting, relies heavily on the coreutils package. They form the bedrock upon which more complex software and operations are built, making them arguably the most critical set of tools for any Linux user.


title: CAVEATS
content:
<b>coreutils</b> commands are so fundamental and widely used that their behavior is often assumed. However, it's important to note that slight behavioral differences can exist between GNU <b>coreutils</b> and other Unix-like implementations (e.g., BSD <b>coreutils</b> found on macOS). While POSIX standards aim for consistency, specific options or default behaviors might vary. Furthermore, shell built-ins (e.g., <b>echo</b>, <b>pwd</b>, <b>cd</b>) might sometimes supersede or complement the <b>coreutils</b> versions of the same name, leading to subtle differences in execution depending on the shell environment.


title: <B><I>KEY UTILITIES WITHIN COREUTILS</I></B>
content:
The <b>coreutils</b> package bundles hundreds of commonly used programs. Here are some of the most frequently invoked categories and examples:<br>- <b>File Utilities:</b> <b>ls</b>, <b>cp</b>, <b>mv</b>, <b>rm</b>, <b>mkdir</b>, <b>rmdir</b>, <b>chmod</b>, <b>chown</b>, <b>ln</b>, <b>df</b>, <b>du</b>, <b>touch</b>. These manage files, directories, and their attributes.<br>- <b>Text Utilities:</b> <b>cat</b>, <b>sort</b>, <b>uniq</b>, <b>wc</b>, <b>head</b>, <b>tail</b>, <b>cut</b>, <b>paste</b>, <b>tr</b>, <b>fmt</b>, <b>split</b>. These are used for viewing, manipulating, and transforming text streams and files.<br>- <b>Shell Utilities & System Information:</b> <b>echo</b>, <b>printf</b>, <b>true</b>, <b>false</b>, <b>test</b>, <b>dirname</b>, <b>basename</b>, <b>pwd</b>, <b>sleep</b>, <b>date</b>, <b>id</b>, <b>whoami</b>, <b>hostname</b>, <b>printenv</b>, <b>seq</b>. These provide basic shell functionality, control flow, and system information.<br>- <b>Data Utilities:</b> <b>base64</b>, <b>cksum</b>, <b>md5sum</b>, <b>sha1sum</b>, <b>factor</b>, <b>numfmt</b>. These handle data encoding, integrity checks, and numerical operations.


title: HISTORY
content:
The <b>coreutils</b> package is a cornerstone of the GNU Project, which was initiated in 1983 by Richard Stallman with the goal of creating a complete Unix-like operating system composed entirely of free software. Many of the utilities in <b>coreutils</b> were early projects of the GNU team, rewritten from scratch to be free software replacements for proprietary Unix commands. Over time, these individual utilities were consolidated into the <b>coreutils</b> package, providing a unified distribution point. They often include enhancements and additional features beyond their traditional Unix counterparts while striving for POSIX compliance. Their continuous development ensures they remain robust and efficient for modern Linux systems.


title: SEE ALSO
content:
util-linux(1): A package containing various essential system utilities not found in coreutils (e.g., fdisk, mount)., findutils(1): Contains utilities for finding files (find) and applying actions (xargs)., grep(1): The grep family of commands for pattern matching., sed(1): Stream editor for filtering and transforming text., awk(1): A powerful text processing language., bash(1): The Bourne Again SHell, which frequently uses coreutils commands.


title: PARAMETERS
content:
<b><I>N/A</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;No recognized parameters for a non-existent standard command.<br><br>


title: DESCRIPTION
content:
The command 'cotton' does not appear to be a recognized or standard utility found in common Linux distributions (e.g., Debian, Ubuntu, CentOS, Fedora, Arch Linux). <br>It lacks a dedicated man page and is not typically part of core utility packages or widely known open-source projects.<br><br>Queries for 'cotton' often refer to: <br> <I>Typographical errors</I> for other commands. <br> <I>Custom scripts or aliases</I> created by individual users or specific system administrators. <br> <I>Application-specific tools</I> that might be named 'cotton' but are not general-purpose system commands. <br> <I>Placeholder names</I> in documentation or examples. <br><br>Without further context, it is not possible to provide an analysis of its functionality, syntax, or usage.


title: CAVEATS
content:
As 'cotton' is not a standard Linux command, any usage or behavior would be entirely dependent on a custom script, alias, or specific application in which it might be defined. Its existence, functionality, and potential side effects cannot be predicted without knowing its actual definition.


title: POSSIBLE MISINTERPRETATION
content:
If you encountered 'cotton' in a specific context, please verify the spelling or seek clarification from the source where the command was mentioned. It might be a component of a larger system or a typo for a well-known command.


title: HISTORY
content:
There is no known official development history or widespread usage for a 'cotton' command in the context of standard Linux utilities.


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message detailing command-line options.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the CouchDB version information.<br><br><b><b>-i</b>, <b>--inetd</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs CouchDB in a mode compatible with <i>inetd</i>, though less common in modern deployments.<br><br><b><b>--config</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration <i>.ini</i> file to load instead of the default.<br><br><b><b>--boot</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative boot file for starting the server.<br><br><b><b>--foreground</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts CouchDB in the foreground, preventing it from daemonizing. Useful for debugging.<br><br><b><b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debug logging output.<br><br>


title: DESCRIPTION
content:
The <b>couchdb</b> command initiates and manages the Apache CouchDB server process. CouchDB is an open-source, schema-free, <i>NoSQL</i> document-oriented database designed for use with web applications. It stores data in <i>JSON</i> format, utilizes <i>JavaScript</i> for indexing and querying with <i>MapReduce</i>, and offers a comprehensive <i>HTTP RESTful API</i> for interaction.<br><br>When executed, the <b>couchdb</b> command typically starts the database server, making it available for client connections. While it can run in the foreground for debugging, it's primarily designed to run as a background service (daemon) in production environments. Its core features include robust data replication, enabling synchronized data across multiple server instances, which is crucial for building scalable, fault-tolerant distributed systems. Configuration is mostly handled via dedicated INI files rather than command-line parameters, simplifying deployment and management.


title: CAVEATS
content:
The <b>couchdb</b> command primarily serves to start the CouchDB server process. Most configuration and management are performed through its <i>HTTP API</i> or by editing its <i>INI</i> configuration files (e.g., <b>local.ini</b> and <b>default.ini</b>). In modern Linux systems, it's highly recommended to manage the CouchDB server as a service using tools like <i>systemd</i> (e.g., <b>systemctl start couchdb</b>) rather than directly invoking the <b>couchdb</b> command for production deployments.


title: PRIMARY INTERACTION
content:
Users typically interact with CouchDB via its <i>RESTful HTTP API</i> using tools like <b>curl</b> or through its web-based administrative user interface, <i>Fauxton</i>.


title: CONFIGURATION
content:
CouchDB's behavior is primarily configured via <i>INI</i> files, such as <b>local.ini</b> and <b>default.ini</b>, located in its installation directory. These files allow detailed control over database settings, networking, security, and more.


title: SERVICE MANAGEMENT
content:
In modern Linux environments, the <b>couchdb</b> process is typically managed by a service manager like <i>systemd</i>. For example, to start the service, one would use <b>systemctl start couchdb</b>; to stop, <b>systemctl stop couchdb</b>; and to check its status, <b>systemctl status couchdb</b>. This is the recommended approach for production environments to ensure proper startup, shutdown, and error handling.


title: HISTORY
content:
CouchDB was initially created by <i>Damien Katz</i> in 2005. It joined the <i>Apache Incubator</i> in 2008 and became a top-level Apache project in 2010. Its development focused on ease of use, robust replication, and a distributed architecture, leveraging <i>HTTP</i> for its API and <i>JSON</i> for data storage, distinguishing it from traditional relational databases.


title: PARAMETERS
content:
<b><i>-d directory</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative Maildir path to scan instead of the default <b>$HOME/Maildir</b> or the path specified by the <b>MAILDIR</b> environment variable. This allows checking mailboxes located at non-standard paths.<br><br>


title: DESCRIPTION
content:
The <i>countmail</i> command is a utility primarily designed to quickly determine and display the number of new email messages within a user's Maildir. It is not a standard, universally available core Linux command, but rather a component of specific mail system packages, most notably <b>maildrop</b>. A Maildir is a directory-based email format where each message is stored as a separate file. When a message is delivered to a Maildir, it initially resides in the 'new' subdirectory. Upon being viewed by a mail client, it's typically moved to the 'cur' subdirectory. <i>countmail</i>'s function is straightforward: it simply counts the number of files present in the 'new' subdirectory of a specified Maildir. If the count is zero, it usually prints nothing; otherwise, it outputs the numeric count to standard output. This makes it ideal for integrating into scripts or status lines for immediate notification of new mail.


title: CAVEATS
content:
<i>countmail</i> is not a part of the standard core Linux utilities; its availability depends on the installation of packages like <b>maildrop</b>. Behavior and specific options might vary significantly if you encounter a custom-scripted version of <i>countmail</i>. It strictly counts messages in the 'new' subdirectory, meaning it will not count messages in 'cur' (even if unread by a mail client) or 'tmp'. It provides no information about message content or read/unread status beyond the simple 'new'/'not new' distinction.


title: USAGE IN STATUS BARS AND PROMPTS
content:
A common use case for <i>countmail</i> is its integration into system status bars (e.g., in window managers like <b>i3</b>, <b>dwm</b>, or <b>bspwm</b>) or within interactive shell prompts (e.g., in <b>bash</b> or <b>zsh</b>). By running <i>countmail</i> periodically, users can display the number of new emails directly in their terminal or desktop status line, providing a non-intrusive and immediate notification of incoming mail without the need to actively check a mail client.


title: HISTORY
content:
The <i>countmail</i> utility is distributed as part of the <b>maildrop</b> mail delivery agent (MDA) package, developed by Sam Varshavchik. <b>maildrop</b> gained popularity as an alternative to traditional MDAs, especially within setups using <b>qmail</b> or <b>Postfix</b>. The inclusion of <i>countmail</i> addresses the practical need for a lightweight, efficient tool to check for new mail status in a Maildir environment, without requiring a full mail client to be launched or complex mailbox parsing to occur.


title: SYNOPSIS
content:
<code>cowsay [options] <I>message</I></code><br><code>cowsay [options] <I>-f cowfile</I> <I>message</I></code><br><code>fortune | cowsay [options]</code>


title: PARAMETERS
content:
<b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Borg mode</b>. Produces a cow that looks like a Borg drone.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Dead mode</b>. Makes the cow's eyes appear 'dead'.<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Greedy mode</b>. Changes the cow's eyes to look greedy.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Stoned mode</b>. Gives the cow a 'stoned' look with droopy eyes.<br><br><b>-t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Tired mode</b>. Displays the cow as tired.<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Wired mode</b>. Makes the cow appear hyper.<br><br><b>-y</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Young mode</b>. Displays a young cow.<br><br><b>-e <I>eyes</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the eye string for the cow. Default is <code>oo</code>. E.g., <code>cowsay -e "==" "Hello"</code>.<br><br><b>-f <I>cowfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the animal to use from the available cowfiles. Use <code>-l</code> to list them. E.g., <code>cowsay -f dragon "Fire!"</code>.<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available cowfiles in the <code>COWPATH</code> directory.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables automatic word wrapping. The message will be printed as is, potentially exceeding terminal width.<br><br><b>-T <I>tongue</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the tongue string for the cow. Default is <code>U</code>. E.g., <code>cowsay -T "xX" "OMG!"</code>.<br><br><b>-u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<b>Upside-down mode</b>. Inverts the cow's appearance. Often combined with other mood options for effect.<br><br><b>-W <I>column</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the column at which the message should be word-wrapped. Default is 40 columns.<br><br>


title: DESCRIPTION
content:
<code>cowsay</code> is a whimsical command-line utility that generates ASCII art pictures of a cow (or other specified animals) saying a message. It takes input text, wraps it in a classic speech bubble, and places it above the ASCII art representation of the animal. The primary function is to make terminal output more engaging or humorous. Users can customize various aspects of the output, including the animal itself by choosing from a collection of "cowfiles," altering the animal's eyes and tongue, or changing its mood (e.g., dead, stoned, greedy). Messages can be provided directly as an command-line argument, or piped from other commands, making <code>cowsay</code> a popular tool for adding a quirky touch to shell scripts, login messages, or simple text outputs. It's widely used in the Unix/Linux community for its entertainment value and ease of integration.


title: CAVEATS
content:
<code>cowsay</code> relies on a collection of ASCII art files (cowfiles) to generate its output. If these files are missing or inaccessible, the command may not function as expected or might only display the default cow. Output can be quite large and might not fit well on very small terminal screens without wrapping issues. While amusing, its use in professional or critical contexts is generally limited to novelty or humor.


title: COWFILES AND CUSTOMIZATION
content:
Cowfiles are simple text files containing the ASCII art definitions for various animals. These files are typically located in <code>/usr/share/cowsay/cowfiles/</code> or <code>/usr/local/share/cowsay/cowfiles/</code>. Users can create their own <code>cowfile</code>s to define new characters or modify existing ones. The <code>COWPATH</code> environment variable can be set to specify additional directories where <code>cowsay</code> should look for <code>cowfile</code>s, allowing for personal collections of ASCII art animals.


title: COMMON USE CASES
content:
<I>Displaying humorous messages:</I><br><code>cowsay "Hello, world!"</code><br><br><I>Combining with <code>fortune</code>:</I><br><code>fortune | cowsay</code><br><br><I>Using different animals:</I><br><code>cowsay -f dragon "Beware of dragons!"</code><br><br><I>Modifying moods and looks:</I><br><code>cowsay -d -e "XX" -T "~" "I'm dead tired."</code><br><br><I>Adding to login greetings:</I><br>Adding <code>fortune | cowsay</code> to your <code>.bashrc</code> or <code>.profile</code> file to display a random message when you log in.


title: HISTORY
content:
The <code>cowsay</code> program was originally written by Tony Monroe in 1997. It quickly gained popularity among Unix and Linux users due to its simple yet entertaining nature. It's often found pre-installed or easily available in package repositories of most major Linux distributions. Its enduring appeal lies in its ability to add a touch of personality and humor to otherwise plain terminal output, making it a staple in many <code>.bashrc</code> files and shell scripts for generating amusing messages. The concept of "cowfiles" for custom animals has allowed for community contributions and further diversification of its capabilities.


title: PARAMETERS
content:
<b><b>-i</b>, <b>--install</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs the specified module(s). This is often implicit when a module name is provided.<br><br><b><b>-f</b>, <b>--force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the installation even if tests fail or if the module is already installed. Use with caution.<br><br><b><b>-D</b>, <b>--distinfo</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays detailed distribution information for the specified module.<br><br><b><b>-l</b>, <b>--local-lib</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures and uses <i>local::lib</i> for installing modules into a user's home directory without root privileges.<br><br><b><b>-r</b>, <b>--reinstall</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reinstalls the specified module(s), even if they appear up-to-date.<br><br><b><b>-g</b>, <b>--get</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only downloads the module distribution; does not build or install.<br><br><b><b>--showdeps</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows dependencies for a given module without installing it.<br><br><b><b>--test</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs tests for a module without installing it.<br><br><b><b>--interactive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces interactive prompts during installation, even if typically non-interactive.<br><br><b><b>--notest</b>, <b>--skiptest</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skips running tests for a module during installation. Not recommended unless you know the module is stable.<br><br><b><b>-a</b>, <b>--autobundle</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a bundle (a list of installed modules) of all currently installed modules that are not part of the standard Perl distribution.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a short help message and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version of the <i>CPAN.pm</i> module and exits.<br><br>


title: DESCRIPTION
content:
The <b>cpan</b> command provides a command-line interface to the Comprehensive Perl Archive Network (CPAN), the central repository for Perl modules. It is the primary tool for installing, testing, and managing Perl modules and their dependencies.<br><br>When invoked, <b>cpan</b> can either drop the user into an interactive shell for more complex operations (like <i>install Module::Name</i>, <i>test Module::Name</i>, <i>look Module::Name</i>) or execute a single command directly from the command line (e.g., <i>cpan Module::Name</i> to install).<br><br><b>cpan</b> automates the entire module installation process, which typically involves downloading the module source, unpacking it, running its <i>Makefile.PL</i> or <i>Build.PL</i> to generate build scripts, compiling C/XS code if present, running tests, and finally installing the module into the Perl library path. It intelligently resolves and downloads dependencies, ensuring that all required modules are present. This greatly simplifies module management for Perl developers and system administrators, making it easy to leverage the vast ecosystem of reusable Perl code. It is an essential utility for anyone working with Perl.


title: CAVEATS
content:
<ul><li><b>Internet Connection Required</b>: <b>cpan</b> needs an active internet connection to download modules from the CPAN mirrors.</li><li><b>Dependency Resolution</b>: While <b>cpan</b> attempts to resolve and install dependencies, complex dependency chains or conflicts can sometimes lead to failures.</li><li><b>Root Privileges</b>: Installing modules system-wide often requires root privileges. Using <i>local::lib</i> (<i>cpan -l</i> or configuring <i>local::lib</i> separately) is recommended for user-specific installations without <b>sudo</b>.</li><li><b>Test Failures</b>: Module tests can sometimes fail due to environment specifics or minor incompatibilities, even if the module itself is functional. The <b>--force</b> option can be used in such cases, but use it judiciously.</li><li><b>Initial Configuration</b>: The first time <b>cpan</b> is run, it often prompts for configuration, including mirror selection and preferred build tools. This initial setup can be daunting for new users.</li></ul>


title: INTERACTIVE SHELL
content:
When <b>cpan</b> is run without any arguments, it enters an interactive shell (e.g., <i>cpan></i>). This shell provides commands like <i>install</i>, <i>test</i>, <i>look</i>, <i>search</i>, <i>i</i>, <i>m</i>, <i>o conf</i>, <i>q</i>, etc., offering more control than single-line invocations.


title: CONFIGURATION
content:
The <b>cpan</b> utility is highly configurable. Users can adjust settings for mirrors, build tools, proxy settings, and installation paths using the <i>o conf</i> command within the interactive shell. Running <i>cpan o conf init</i> will guide a user through the initial setup process.


title: LOCAL::LIB INTEGRATION
content:
For users who do not have root access or prefer to keep their Perl modules separate from the system-wide installation, <b>cpan</b> integrates seamlessly with <i>local::lib</i>. Running <i>cpan -l</i> or setting up <i>local::lib</i> environment variables allows modules to be installed into a user's home directory.


title: HISTORY
content:
The Comprehensive Perl Archive Network (CPAN) was founded in 1995 by Jarkko Hietaniemi. It quickly became the definitive repository for Perl modules, revolutionizing how Perl developers share and reuse code. The <i>CPAN.pm</i> module, which the <b>cpan</b> command-line utility wraps, was developed to provide an interactive interface to this vast archive. Over the years, <b>cpan</b> has evolved significantly, adding features for dependency management, testing, and configuration. Its development has been driven by the Perl community, continuously adapting to new Perl versions and ecosystem needs. It remains an indispensable tool, central to the Perl development workflow, enabling rapid development by providing access to tens of thousands of pre-built solutions.


title: PARAMETERS
content:
<b>-t, --type <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the desired distribution type (e.g., <b>rpm</b>, <b>deb</b>, <b>tgz</b>, <b>native</b>).<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output to show detailed information during the build process.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force operations, such as rebuilding modules even if they appear up-to-date.<br><br><b>--test</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run the module's test suite before proceeding with the distribution build.<br><br><b>--install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to install the generated distribution package immediately after creation.<br><br><b>--builddir <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define a custom directory for temporary build files and intermediate outputs.<br><br><b>--no-deps</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevent <i>cpan2dist</i> from resolving or installing module dependencies.<br><br><b>--mirror <url></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a particular CPAN mirror URL to fetch modules from.<br><br><b>--sudo</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <b>sudo</b> for commands requiring elevated privileges during build or installation.<br><br><b>--perl <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify an alternative Perl executable to be used for the build process.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a brief help message and exit.<br><br>


title: DESCRIPTION
content:
<i>cpan2dist</i> is a powerful command-line utility designed to simplify the packaging of Perl modules from CPAN into system-native distribution formats. It acts as an essential bridge between the vast Perl module ecosystem and your operating system's package management system (e.g., RPM for Red Hat-based systems, DEB for Debian-based systems).<br><br>The command automates the entire process: it resolves and fetches module dependencies, downloads the specified CPAN module, configures it using standard Perl build tools (like <i>ExtUtils::MakeMaker</i> or <i>Module::Build</i>), and finally compiles and packages it into the chosen distribution format. This allows system administrators and developers to deploy Perl modules consistently and manage them alongside other system software, simplifying updates and ensuring environmental stability.<br><br>Beyond simply creating packages, <i>cpan2dist</i> can also test modules before packaging and even attempt to install the resulting distribution directly, providing a comprehensive solution for Perl module deployment.


title: CAVEATS
content:
<i>cpan2dist</i> relies heavily on the presence and correct configuration of underlying system packaging tools (e.g., <b>rpmbuild</b> for RPMs, <b>dpkg-buildpackage</b> for DEBs). These tools must be installed on your system for <i>cpan2dist</i> to function for their respective package types. Some Perl modules with complex external (non-Perl) dependencies or non-standard build processes might not package correctly. Root privileges may be required for installing the generated packages or for certain build steps.


title: SUPPORTED DISTRIBUTION TYPES
content:
<i>cpan2dist</i> supports a variety of output formats, specified using the <b>--type</b> option:<br><b>rpm</b>: Creates a Red Hat Package Manager (<b>.rpm</b>) file, widely used on RHEL, CentOS, Fedora.<br><b>deb</b>: Generates a Debian package (<b>.deb</b>) file, standard for Debian, Ubuntu, and derivatives.<br><b>tgz</b>: Produces a compressed tarball (<b>.tar.gz</b>), a common generic archive format.<br><b>native</b>: Performs a direct <b>make install</b> without creating a separate package file, installing the module directly into the Perl installation prefix.


title: CONFIGURATION AND INTEGRATION
content:
<i>cpan2dist</i> leverages the robust configuration system of <i>CPANPLUS</i>. Users can customize various aspects of module fetching, building, and installation through the <i>CPANPLUS</i> shell or its configuration files, ensuring that <i>cpan2dist</i> operates according to specific project or system requirements, including preferred CPAN mirrors and build toolchain options.


title: HISTORY
content:
<i>cpan2dist</i> is an integral part of the <i>CPANPLUS</i> project, which was developed as a more modern, extensible, and user-friendly alternative to the traditional <i>CPAN.pm</i> shell. Its inception addressed the growing need for better integration between Perl's vast module ecosystem and standard operating system package management tools. The core packaging logic is provided by the <i>CPANPLUS::Dist::Build</i> module, allowing <i>cpan2dist</i> to adapt to various distribution formats and streamline the deployment of Perl applications in controlled environments.


title: SYNOPSIS
content:
<b>cpanp</b> [<i>OPTIONS</i>] [<i>COMMAND</i>] [<i>MODULE_OR_ARGUMENTS ...</i>]<br><br>Common <i>COMMANDs</i>:<br>&nbsp;&nbsp;<b>install</b> <i>Module::Name</i><br>&nbsp;&nbsp;<b>upgrade</b> <i>Module::Name</i><br>&nbsp;&nbsp;<b>search</b> <i>keyword</i><br>&nbsp;&nbsp;<b>shell</b><br>&nbsp;&nbsp;<b>autobuild</b><br>&nbsp;&nbsp;<b>info</b> <i>Module::Name</i><br>&nbsp;&nbsp;<b>lookup</b> <i>Module::Name</i><br>&nbsp;&nbsp;<b>rebuild</b>


title: PARAMETERS
content:
<b>-i, --install</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install specified Perl modules.<br><br><b>-u, --upgrade</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Upgrade specified Perl modules to their latest versions.<br><br><b>-s, --search</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Search the CPAN index for modules matching a keyword.<br><br><b>-e, --shell</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enter an interactive cpanp shell for advanced operations.<br><br><b>-b, --autobuild</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Build and install modules without prompting.<br><br><b>-f, --force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force operations, e.g., reinstalling modules or proceeding despite warnings.<br><br><b>-n, --noconfirm</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not ask for confirmation; assume 'yes' to all prompts.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Increase verbosity of output.<br><br><b>-D, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug output for detailed troubleshooting.<br><br><b>-F, --force-install-with-tests</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force installation even if tests fail.<br><br><b>--show-config</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the current CPANPLUS configuration.<br><br><b>--test</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Only run tests for a module, do not install.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a short help message and exit.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information and exit.<br><br>


title: DESCRIPTION
content:
<b>cpanp</b> is a command-line utility for installing, managing, and interacting with Perl modules from the Comprehensive Perl Archive Network (CPAN). It serves as an alternative, and often more user-friendly, interface to the traditional <b>cpan</b> shell. Built upon the <i>CPANPLUS</i> Perl module, <b>cpanp</b> aims to simplify the process of acquiring and deploying Perl software by automating common tasks such as fetching module distributions, resolving dependencies, running tests, and performing installations. It provides an intuitive command-line interface, offering commands for installing new modules, upgrading existing ones, searching the CPAN repository, and even entering an interactive shell for more complex operations. <b>cpanp</b> handles dependency chains automatically, prompting the user for decisions when necessary, but also allowing for non-interactive operations. Its design focuses on ease of use and robust management of the Perl module ecosystem.


title: CAVEATS
content:
<b>cpanp</b> relies entirely on the underlying <i>CPANPLUS</i> Perl module, which must be installed and correctly configured. While designed for user-friendliness, its initial setup or advanced configuration (via <i>CPANPLUS::Config::User.pm</i>) can sometimes be complex for new users. Although robust, <b>cpanp</b> may occasionally be slower than the more minimalist <b>cpan</b> client for simple module installations due to its more comprehensive feature set and dependency management overhead. Furthermore, <i>CPANPLUS</i> and thus <b>cpanp</b> have seen less active development compared to the core <b>cpan</b> client in recent years, though it remains a viable and stable tool.


title: CONFIGURATION
content:
<b>cpanp</b>'s behavior is managed by the underlying <i>CPANPLUS</i> configuration. This configuration is typically stored in a Perl module file, most commonly located at <i>~/.cpanplus/lib/CPANPLUS/Config/User.pm</i>. This file allows users to define default mirrors, build preferences, testing options, and other customizations. If this file doesn't exist, <b>cpanp</b> will guide the user through an initial setup process.


title: INTERACTIVE SHELL
content:
Invoking <b>cpanp shell</b> (or <b>cpanp -e</b>) opens an interactive prompt similar to the traditional <b>cpan</b> shell. This mode allows users to execute multiple commands (e.g., 'install', 'test', 'info') without repeatedly typing 'cpanp', offering a persistent environment for module management and exploration.


title: MODULE INSTALLATION PROCESS
content:
When you request to install a module, <b>cpanp</b> typically performs the following steps: <br>1. <i>Download</i>: Fetches the module distribution from a configured CPAN mirror. <br>2. <i>Unpack</i>: Extracts the distribution archive (usually a .tar.gz file). <br>3. <i>Dependencies Check</i>: Identifies and resolves any required prerequisite modules, potentially installing them first. <br>4. <i>Build</i>: Executes the `perl Makefile.PL` or `Build.PL` script, followed by `make` or `Build` (if applicable). <br>5. <i>Test</i>: Runs the module's test suite (`make test` or `Build test`). <br>6. <i>Install</i>: Places the module files in the appropriate Perl library directories (`make install` or `Build install`).


title: HISTORY
content:
<b>cpanp</b> emerged as part of the <i>CPANPLUS</i> project, which began development in the early 2000s (around 2003-2004). Its primary motivation was to provide a more modern, robust, and programmatic alternative to the original <b>cpan</b> shell, which, while functional, was often perceived as less user-friendly and harder to integrate into automated scripts. <i>CPANPLUS</i> aimed to offer better dependency resolution, more configurable options, and a cleaner interface, with <b>cpanp</b> being its flagship command-line utility. It quickly gained popularity among Perl developers seeking a more streamlined and automated way to manage their module installations.


title: SYNOPSIS
content:
<b>cpdf</b> [<i>options</i>] <i>input.pdf</i> [<i>pages</i>] [<i>operator</i>] [<i>output.pdf</i>]<br><b>cpdf</b> -merge <i>file1.pdf file2.pdf</i> -o <i>output.pdf</i><br><b>cpdf</b> -split <i>input.pdf</i> -o <i>page%d.pdf</i><br><b>cpdf</b> -encrypt <i>input.pdf</i> -owner-pwd <i>ownerpass</i> -user-pwd <i>userpass</i> -o <i>encrypted.pdf</i>


title: PARAMETERS
content:
<b><b>-merge</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Merges multiple PDF files or pages into a single output PDF.<br><br><b><b>-split</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Splits a PDF file into individual pages or specified page ranges.<br><br><b><b>-encrypt</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encrypes a PDF with user and/or owner passwords, setting permissions for printing, copying, etc.<br><br><b><b>-decrypt</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decrypts an encrypted PDF, requiring the correct password.<br><br><b><b>-rotate</b> <i>degrees</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Rotates specified pages by a given angle (e.g., 90, 180, 270).<br><br><b><b>-scale</b> <i>factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales page content by a specified factor (e.g., 0.5 for half size, 2 for double).<br><br><b><b>-add-text</b> <i>"text"</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds text content to specified pages at a given position and with specified formatting.<br><br><b><b>-add-image</b> <i>image.png</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds an image (e.g., PNG, JPEG) to specified pages.<br><br><b><b>-remove-pages</b> <i>pages</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes specified pages or page ranges from a PDF.<br><br><b><b>-compress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compresses the PDF to reduce file size, typically by optimizing streams and removing redundant data.<br><br><b><b>-decompress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Decompresses streams within a PDF, which can aid in debugging or advanced editing.<br><br><b><b>-stamp</b> <i>stamp.pdf</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overlays another PDF (stamp) onto the target PDF's pages, often used for watermarking or adding headers/footers.<br><br><b><b>-impose</b> <i>N-up</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arranges multiple logical pages onto a single physical page (e.g., 2-up, 4-up for printing brochures).<br><br><b><b>-o</b> <i>output.pdf</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file name for the operation.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides more detailed output during execution, useful for debugging.<br><br><b><b>-version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current version of <b>cpdf</b>.<br><br>


title: DESCRIPTION
content:
<b>cpdf</b> is a high-performance command-line utility for manipulating PDF files. Developed by Coherent PDF, it offers a wide range of functionalities including merging, splitting, encrypting, decrypting, rotating, scaling, watermarking, stamping, and text/image insertion.<br>Unlike some other PDF tools, <b>cpdf</b> is designed for speed and reliability, making it suitable for scripting, automation, and batch processing tasks. It can perform complex operations with simple commands, managing pages, metadata, and security settings with efficiency. Its comprehensive feature set makes it a go-to tool for developers and system administrators working with PDF documents in a Linux environment.


title: CAVEATS
content:
<b>cpdf</b> is a commercial product, though a free version is typically available for non-commercial use on Linux distributions. Ensure you are using the appropriate license for your intended purpose.<br>While powerful, its extensive array of options can lead to a steep learning curve. It's not always pre-installed and might require manual installation depending on your distribution. Error messages can sometimes be terse, requiring careful command construction.


title: <I>LICENSING AND AVAILABILITY</I>
content:
While often available in Linux repositories, it's important to note that the freely distributable version of <b>cpdf</b> is for non-commercial use only. For commercial applications, a paid license is required. This distinction is crucial for organizations deploying <b>cpdf</b> in production environments.


title: <I>PERFORMANCE</I>
content:
<b>cpdf</b> is highly optimized for performance, making it exceptionally fast for large PDF files or batch operations. Its efficiency in handling complex PDF structures is a significant advantage over some other tools that might struggle with very large or intricate documents.


title: HISTORY
content:
<b>cpdf</b> is developed by Coherent PDF, a company focused on PDF software solutions. It emerged as a high-performance, reliable command-line tool, distinguishing itself with its speed and comprehensive feature set compared to some open-source alternatives.<br>Its development has focused on providing robust capabilities for automated PDF processing, making it a favorite for server-side operations and complex scripting tasks. The tool has been consistently updated to support new PDF standards and functionalities.


title: SYNOPSIS
content:
While <b>cpgr</b> is not a direct command, its implied usage follows the syntax of <b>cp</b> with the specified options:<br><br><b>cp -gr</b> [<i>OPTION</i>]... <i>SOURCE</i>... <i>DIRECTORY</i><br><b>cp -gr</b> [<i>OPTION</i>]... <i>SOURCE DESTINATION</i><br><br><i>Examples:</i><br><b>cp -gr</b> <i>/path/to/source_directory /path/to/destination_directory</i><br><b>cp -gr</b> <i>file1.txt file2.txt /path/to/target_directory</i> (Copies files and preserves group if source is a file)


title: PARAMETERS
content:
<b>SOURCE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the file(s) or directory(ies) to be copied. Multiple sources can be specified if the destination is a directory.<br><br><b>DESTINATION</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The target path where the source(s) will be copied. Can be a new file name (for a single source) or an existing directory (for single or multiple sources).<br><br><b>-g, --preserve=group</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserves the group ownership of the source files/directories in the destination. This operation typically requires root privileges or the invoking user to be a member of the target group.<br><br><b>-r, -R, --recursive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies directories and their contents (subdirectories and files) recursively. This option is essential for copying entire folder structures.<br><br><b>-a, --archive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies in archive mode, preserving as much as possible of the original file's attributes: permissions, timestamps, context, links (does not follow symlinks), etc. This option implies <b>-dR --preserve=all</b>, and often encompasses the functionality of <b>-g</b> and <b>-r</b>.<br><br><b>-p, --preserve=mode,ownership,timestamps</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserves the mode (permissions), ownership (user and group), and timestamps of the source file/directory in the copy.<br><br><b>-v, --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explains what is being done by printing the name of each file or directory as it is copied.<br><br><b>--target-directory=DIRECTORY</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the destination DIRECTORY explicitly. This is useful when sources could be confused with a destination, for instance when copying a single source named 'target_dir'.<br><br>


title: DESCRIPTION
content:
The command <b>cpgr</b> is <i>not a standard Linux command</i>. It is highly probable that it is a shorthand or a common typo for the <b>cp</b> command used with the <b>-g</b> and <b>-r</b> (or <b>-R</b>) options. The <b>cp</b> (copy) command is a fundamental utility in Unix-like operating systems used for copying files and directories.<br><br>When invoked as <b>cp -gr</b>, it performs two main functions:<br><br><i>1. Recursive Copy (<b>-r</b> or <b>-R</b>):</i> This option allows <b>cp</b> to copy directories and their entire contents (subdirectories, files, etc.). Without this option, <b>cp</b> can only copy individual files or an empty directory, and will error out if you try to copy a directory.<br><br><i>2. Preserve Group Ownership (<b>-g</b>):</i> This option instructs <b>cp</b> to preserve the group ownership of the source files/directories in the copied destination. By default, new files and directories created by <b>cp</b> typically inherit the group of the user executing the command, or the default group of the parent directory. The <b>-g</b> option ensures that the original group associated with the source file/directory is maintained in the copy, provided the user has the necessary permissions (typically root privileges or membership in the target group).


title: CAVEATS
content:
Using <b>cp -gr</b>, especially with the <b>-g</b> option, requires careful consideration:<br><br>1. <i>Permissions:</i> Preserving group ownership (<b>-g</b>) often requires the user executing the command to have root privileges or to be a member of the target group on the destination file system. If not, the group ownership will default to the effective group ID of the user or the default group of the parent directory.<br><br>2. <i>Disk Space:</i> Copying large directories recursively can consume significant disk space on the destination.<br><br>3. <i>Symbolic Links:</i> By default, <b>cp -r</b> copies the contents of symbolic links to directories (i.e., it dereferences them). To copy the symbolic link itself, use the <b>-P</b> or <b>--no-dereference</b> option. The <b>-a</b> (archive) option implies <b>-P</b>.<br><br>4. <i>Atomic Operations:</i> <b>cp</b> is not atomic; if interrupted, it may leave partial or corrupted copies. For critical or large transfers, <b>rsync</b> is often a more robust choice.


title: DIFFERENCE BETWEEN -R AND -R
content:
For the <b>cp</b> command, the <b>-r</b> and <b>-R</b> options are typically synonymous and both denote recursive copying of directories. There is generally no functional difference between them for <b>cp</b> on modern Linux systems. Historically, <b>-R</b> was sometimes used to indicate a preference for copying symbolic links as-is (not dereferencing them), but this behavior is now primarily controlled by the <b>-P</b> or <b>--no-dereference</b> options, or implied by <b>-a</b> (archive mode).


title: OWNERSHIP AND PERMISSIONS
content:
When copying files and directories with <b>cp</b> without specific preservation options, the new copies will usually have the ownership (user and group) of the user executing the command and default permissions based on the user's umask. The <b>-g</b> option specifically preserves the group ownership. To preserve user ownership as well, the <b>-p</b> option (which preserves mode, ownership, and timestamps) or the more comprehensive <b>-a</b> (archive) option should be used. Preserving ownership typically requires root privileges, as ordinary users cannot arbitrarily set the ownership of files to another user.


title: HISTORY
content:
The <b>cp</b> command is one of the oldest and most fundamental utilities in the Unix operating system, dating back to its earliest versions in the 1970s. Its core functionality for copying files has remained largely consistent throughout its history. Options like <b>-g</b> (group preservation) and <b>-r</b> (recursive) were added as the system evolved to handle more complex file system operations and directory structures. Its inclusion in POSIX standards ensures its ubiquitous presence and consistent behavior across various Unix-like systems, including Linux.


title: SEE ALSO
content:
<b>cp(1)</b>: The core copy command., <b>mv(1)</b>: Move or rename files and directories., <b>rm(1)</b>: Remove files or directories., <b>ln(1)</b>: Make links between files., <b>rsync(1)</b>: A more powerful and flexible tool for copying and synchronizing files, especially across networks, with options for preserving attributes, incremental updates, and resuming transfers.


title: SYNOPSIS
content:
<b>cpio</b> <i>-o</i> [<i>options</i>] &lt; <i>name-list</i> &gt; <i>archive</i><br><b>cpio</b> <i>-i</i> [<i>options</i>] [<i>pattern...</i>] &lt; <i>archive</i><br><b>cpio</b> <i>-p</i> [<i>options</i>] <i>directory</i> &lt; <i>name-list</i>


title: PARAMETERS
content:
<b><i>-o</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create archive mode. Reads filenames from stdin; writes archive to stdout (or file specified by <i>-F</i>).<br><br><b><i>-i</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Extract archive mode. Reads archive from stdin (or file via <i>-F</i>); extracts files. Optional <i>pattern</i> arguments filter extracted files.<br><br><b><i>-p</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pass-through mode. Reads filenames from stdin; copies them to the specified <i>directory</i> without intermediate archive creation.<br><br><b><i>-v</i>, <i>--verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose mode. Lists processed files, showing detailed information in create/extract modes or names in pass-through mode.<br><br><b><i>-d</i>, <i>--make-directories</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Create leading directories as needed during extraction or pass-through.<br><br><b><i>-u</i>, <i>--unconditional</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unconditionally copy/extract files, replacing newer files with older ones.<br><br><b><i>-m</i>, <i>--preserve-modification-time</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Preserve original modification times of files during extraction/copying.<br><br><b><i>-a</i>, <i>--reset-access-time</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reset access times of input files after reading.<br><br><b><i>-L</i>, <i>--dereference</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Follow symbolic links; archive/copy the files they point to, not the links themselves.<br><br><b><i>-H <i>format</i></i>, <i>--format=<i>format</i></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the archive format, e.g., <i>newc</i>, <i>crc</i>, <i>bin</i>, <i>odc</i>, <i>ascii</i>.<br><br><b><i>-F <i>archive</i></i>, <i>--file=<i>archive</i></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the specified <i>archive</i> file instead of standard input/output.<br><br><b><i>-R <i>owner[:group]</i></i>, <i>--owner=<i>owner[:group]</i></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set ownership of created files. Requires root privileges.<br><br><b><i>--block-size=<i>BLOCK_SIZE</i></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set I/O block size (<i>BLOCK_SIZE</i> * 512 bytes). Default is 10 blocks (5120 bytes).<br><br><b><i>--null</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filenames are null-terminated in <i>-o</i> or <i>-p</i> mode. Essential when piping from <i>find -print0</i>.<br><br><b><i>--no-absolute-filenames</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Convert absolute filenames to relative ones during extraction to prevent accidental system file overwrites.<br><br>


title: DESCRIPTION
content:
<i>cpio</i> (copy in/out) is a command-line utility for archiving files and directories. It copies files into or out of a <i>cpio</i> archive, or copies files from one directory tree to another. Unlike <i>tar</i>, <i>cpio</i> typically reads a list of filenames from standard input (often piped from <i>find</i>), providing flexible file selection. It supports various archive formats, notably <i>newc</i>, which is widely used for Linux <i>initramfs</i> images. It operates in three main modes: creating archives (<i>-o</i>), extracting from archives (<i>-i</i>), and pass-through copying (<i>-p</i>).


title: CAVEATS
content:
When extracting archives, be cautious with absolute filenames (e.g., paths starting with <i>/</i>) if the archive was created with them. Using <i>--no-absolute-filenames</i> is recommended to prevent accidental overwrites of system files. <i>cpio</i> typically expects a list of null-terminated filenames when piped from commands like <i>find -print0</i>, especially for filenames containing spaces or special characters.


title: COMMON USAGE WITH <I>FIND</I>
content:
A very common pattern for creating a <i>cpio</i> archive is to pipe the output of the <i>find</i> command into <i>cpio</i>. To handle filenames with spaces or special characters correctly, it is crucial to use <i>find -print0</i> and <i>cpio --null</i>.<br><br><b>Example:</b><br><i>find . -print0 | cpio -o --null -H newc &gt; myarchive.cpio</i><br><br>This command finds all files and directories starting from the current directory, prints their names separated by null characters, and pipes this list to <i>cpio</i>, which then creates a <i>newc</i> format archive named <i>myarchive.cpio</i>.


title: ARCHIVE FORMATS
content:
<i>cpio</i> supports various archive formats. The most commonly used in modern Linux environments are:<br><ul><li><b>newc</b>: The "new" portable format, widely used for Linux <i>initramfs</i> images.</li><li><b>crc</b>: Similar to <i>newc</i> but includes a checksum for data integrity.</li><li><b>bin</b>: The obsolete binary format.</li><li><b>odc</b>: The old ASCII format, also known as 'old character'.</li><li><b>ascii</b>: A more portable ASCII format.</li></ul>


title: HISTORY
content:
<i>cpio</i> is one of the oldest archiving utilities in Unix-like systems, tracing its origins back to the PWB/UNIX (Programmer's Workbench) systems of the 1970s. It was designed to copy file archives between different formats. While <i>tar</i> later became more dominant for general-purpose archiving, <i>cpio</i> maintained its niche, particularly due to its ability to read filenames from standard input, making it highly flexible when combined with other tools like <i>find</i>. Its 'newc' format is notably used for Linux <i>initramfs</i> images.


title: PARAMETERS
content:
<b>-D <I>macro</I>[=<I>definition</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define a <I>macro</I> with an optional <I>definition</I> before preprocessing begins. Equivalent to a <I>#define</I> directive at the beginning of the file.<br><br><b>-U <I>macro</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Undefine a previously defined <I>macro</I>. Equivalent to a <I>#undef</I> directive.<br><br><b>-I <I>dir</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <I>dir</I> to the list of directories to be searched for header files during <I>#include</I> directives. Directories are searched in the order specified.<br><br><b>-include <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Include the contents of <I>file</I> before processing the main input file. This is useful for including common definitions or configuration headers.<br><br><b>-P</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inhibit the generation of <I>#line</I> directives. This results in cleaner output, but it loses information about original file and line numbers, which can complicate debugging.<br><br><b>-C</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not strip C-style comments from the output. By default, <b>cpp</b> removes comments.<br><br><b>-M</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a list of <I>make</I> rules suitable for recompilation from the command line. This option outputs dependency information (e.g., all header files included by the source) to standard output.<br><br><b>-o <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify <I>file</I> as the output file name. If omitted, the output is sent to standard output.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the version number of <b>cpp</b>.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for <b>cpp</b> command-line options.<br><br>


title: DESCRIPTION
content:
The <b>cpp</b> command, an acronym for <I>C Preprocessor</I>, is the first phase of compilation for C, C++, and Objective-C source code. While rarely invoked directly by users, it is an essential component of the GNU Compiler Collection (GCC), typically run automatically by the <b>gcc</b> command.<br><br>Its primary functions include:<br><b>Header Inclusion</b>: Processing <I>#include</I> directives to insert the contents of specified header files into the source code. It searches for headers in standard system directories and user-specified paths.<br><b>Macro Expansion</b>: Performing text substitution for <I>#define</I> macros, replacing macro names with their defined values or code snippets.<br><b>Conditional Compilation</b>: Handling directives like <I>#ifdef</I>, <I>#ifndef</I>, <I>#if</I>, <I>#else</I>, and <I>#endif</I> to selectively include or exclude blocks of code based on conditions, useful for platform-specific code or debugging.<br><b>Other Directives</b>: Processing directives such as <I>#line</I> (to control line numbers for debugging), <I>#error</I> (to issue compilation errors), and <I>#warning</I> (to issue warnings).<br><br>The output of <b>cpp</b> is a single, expanded source file that is then passed to the compiler (e.g., <b>cc1</b> for C) for syntax analysis and code generation. It does not perform any syntax checking or code generation itself.


title: CAVEATS
content:
The <b>cpp</b> command is typically an internal component of the compiler suite (like GCC) and is rarely executed directly by users. When users compile C/C++ code, <b>gcc</b> automatically invokes <b>cpp</b> as part of its multi-stage compilation process. Direct invocation is mostly for debugging preprocessor issues, such as examining macro expansions or include paths. Its output is not directly executable and requires further processing by the compiler, assembler, and linker.


title: USAGE IN GCC COMPILATION
content:
When you run <b>gcc <I>source.c</I></b>, the compilation process typically involves four stages: 1. <b>Preprocessing</b> (handled by <b>cpp</b>), 2. <b>Compilation</b> (generating assembly code), 3. <b>Assembly</b> (converting assembly to machine code), and 4. <b>Linking</b> (combining object files and libraries). You can explicitly invoke only the preprocessing stage with <b>gcc -E <I>source.c</I> -o <I>output.i</I></b>, which essentially runs <b>cpp</b> on the source file.


title: LINEMARKER DIRECTIVES
content:
By default, <b>cpp</b> inserts <I>#line</I> directives (e.g., <I># 1 "file.c"</I>) into its output. These directives inform the subsequent compiler stage about the original source file and line number for the code that follows. This is crucial for accurate error reporting and debugging, as it allows tools to trace errors back to the original source location even after preprocessing transformations.


title: HISTORY
content:
The concept of a C preprocessor has been integral to the C language since its inception in the early 1970s. It provided essential features like file inclusion and macro definitions that were crucial for code modularity and abstraction in a low-level language. The GNU C Preprocessor (GCPP), which is part of the GNU Compiler Collection (GCC), is the most widely used implementation on Linux systems. It has evolved to conform to the C and C++ language standards (e.g., C99, C11, C++98, C++11, C++17) and supports numerous extensions while maintaining backward compatibility. Its development tracks closely with the evolution of the GCC compiler suite itself.


title: PARAMETERS
content:
<b><b>-D</b><i>&lt;macro&gt;</i>[=<i>&lt;value&gt;</i>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Define a macro with an optional value. If no value is specified, the macro is defined as '1'.<br><br><b><b>-U</b><i>&lt;macro&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Undefine a macro, even if it was previously defined on the command line or in the source code.<br><br><b><b>-I</b><i>&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add <i>&lt;dir&gt;</i> to the list of directories searched for header files during file inclusion.<br><br><b><b>-M</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output a rule suitable for <b>make</b> describing the dependencies of the main source file (i.e., its header files). System headers are included.<br><br><b><b>-MM</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <b>-M</b>, but excludes system header files from the dependency list.<br><br><b><b>-MD</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Like <b>-M</b>, but also compile the source file. The dependencies are written to a file named <i>&lt;file&gt;.d</i> by default, or specified by <b>-MF</b>.<br><br><b><b>-MMD</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Like <b>-MM</b>, but also compile the source file. Dependencies are written to a <i>.d</i> file, excluding system headers.<br><br><b><b>-MF</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with <b>-M</b>, <b>-MM</b>, <b>-MD</b>, or <b>-MMD</b>, specifies the output file for the dependency information.<br><br><b><b>-MT</b> <i>&lt;target&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Change the target of the rule emitted by <b>-M</b> or <b>-MM</b>. Useful for custom build systems.<br><br><b><b>-MQ</b> <i>&lt;target&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Like <b>-MT</b>, but quotes special characters in <i>&lt;target&gt;</i> for use in <b>make</b>files.<br><br><b><b>-P</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inhibit generation of <i># line</i> markers. Useful for producing cleaner output for human inspection or other tools.<br><br><b><b>-C</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not discard comments during preprocessing. Comments will be preserved in the output.<br><br><b><b>-CC</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Like <b>-C</b>, but also preserve comments that appear within macro arguments, even if the macro expands to nothing.<br><br><b><b>-E</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run only the preprocessor. This is often implicit when invoking <b>cpp-4.8</b> directly.<br><br><b><b>-H</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print the name of each header file as it is used, indicating the order of inclusion.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing the command's internal components, search paths, and other diagnostic information.<br><br><b><b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the preprocessor's version information and exit.<br><br><b><b>-std=</b><i>&lt;standard&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Conform to the specified C or C++ language standard (e.g., <i>c99</i>, <i>c++03</i>). This affects specific preprocessor behaviors related to the standard.<br><br>


title: DESCRIPTION
content:
The <b>cpp-4.8</b> command invokes the C Preprocessor component from the GNU Compiler Collection (GCC) version 4.8. It is the first stage of the compilation process for C, C++, and Objective-C programs. Its primary role is to handle preprocessing directives embedded in source code, transforming the original source file into an intermediate form before actual compilation.<br><br>Key functions of the preprocessor include:<br><i>Macro Expansion:</i> Replacing defined macros with their corresponding text.<br><i>File Inclusion:</i> Incorporating content from specified header files (e.g., via <i>#include</i> directives).<br><i>Conditional Compilation:</i> Including or excluding blocks of code based on conditions (e.g., using <i>#if</i>, <i>#ifdef</i>, <i>#ifndef</i>, <i>#else</i>, <i>#elif</i>, <i>#endif</i>).<br><i>Line Control:</i> Generating <i># line</i> directives to aid debuggers and tools by indicating the original source file and line numbers.


title: CAVEATS
content:
The <b>cpp-4.8</b> command refers to a specific version (4.8) of the GNU C Preprocessor. On modern Linux distributions, the default <b>cpp</b> command typically points to a much newer GCC version. This specific version might be present on older systems or within environments configured for legacy software development.<br><br>While <b>cpp-4.8</b> functions as a standalone preprocessor, it is most commonly invoked implicitly by the <b>gcc</b> or <b>g++</b> compiler driver commands as part of the overall compilation process. Its output is typically fed directly into the next stage of compilation (the compiler itself), rather than being stored as a separate file unless specifically requested with options like <b>-E</b> and redirection.


title: PREPROCESSING STAGES
content:
The preprocessing stage is the first of several stages in the compilation of C/C++/Objective-C code. The typical sequence is:<br>1. <i>Preprocessing</i> (by <b>cpp</b>): Handles directives, macros, and includes.<br>2. <i>Compilation</i> (by <b>cc1</b>/<b>cc1plus</b>): Converts preprocessed code into assembly code.<br>3. <i>Assembly</i> (by <b>as</b>): Converts assembly code into machine code (object files).<br>4. <i>Linking</i> (by <b>ld</b>): Combines object files and libraries into an executable or shared library.


title: OUTPUT FORMAT
content:
When <b>cpp-4.8</b> is run with <b>-E</b>, its output is a single, expanded source file. This file contains all included header content, all macro expansions, and conditionally compiled code. By default, it also includes <i># line</i> directives that specify the original source file and line number for each line of code, which is crucial for debugging and error reporting later in the compilation process.


title: HISTORY
content:
The concept of a preprocessor dates back to the early days of the C language. Originally, it was often a separate program or a very simple initial pass. With the advent of the GNU Compiler Collection (GCC), the C preprocessor (<b>cpp</b>) became an integrated, yet distinct, component.<br><br>GCC's development has been continuous, with major version releases marking significant advancements. Version 4.8, released around 2013, was a stable and widely adopted release of GCC, introducing new features and improved C++11/C++14 support. The <b>cpp-4.8</b> command specifically identifies the preprocessor binary associated with that particular GCC release. While newer GCC versions (and thus newer <b>cpp</b> versions) exist, the core functionality and syntax of the C preprocessor have remained largely consistent since the C standard (C89/C90), ensuring broad compatibility across different <b>cpp</b> versions for standard C/C++ code.


title: PARAMETERS
content:
<b>--enable=<checks></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enables specific checks or categories.</i> Common values: <b>all</b>, <b>style</b>, <b>performance</b>, <b>portability</b>, <b>information</b>, <b>unusedFunction</b>, <b>missingInclude</b>.<br><br><b>-I <dir> or --include=<dir></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Adds a directory to the include path.</i> Useful for resolving header files.<br><br><b>-D <id> or --define=<id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Defines a preprocessor macro.</i> Simulates compiler definitions.<br><br><b>-U <id> or --undef=<id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Undefines a preprocessor macro.</i><br><br><b>--std=<id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the C/C++ standard.</i> E.g., <b>c++11</b>, <b>c99</b>, <b>c++20</b>.<br><br><b>-j <jobs> or --jobs=<jobs></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Number of concurrent analysis jobs.</i> Speeds up analysis on multi-core systems.<br><br><b>--xml</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Outputs results in XML format.</i> Facilitates integration with other tools.<br><br><b>--xml-version=<version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the XML output version.</i><br><br><b>--check-config</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Checks project configuration and include paths.</i> Helps debug setup issues.<br><br><b>--force</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Forces analysis even if include paths are missing.</i> May lead to more false positives.<br><br><b>--suppress=<id></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Suppresses specific warnings by ID.</i> Can be used multiple times.<br><br><b>--language=<lang></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Forces analysis as C or C++.</i> Values: <b>c</b> or <b>c++</b>.<br><br><b>-q or --quiet</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Suppresses progress messages.</i> Only errors/warnings are printed.<br><br><b>-v or --verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Prints verbose information.</i> Includes progress and detailed analysis info.<br><br><b>--project=<file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Analyzes a project defined in a build file.</i> E.g., <b>.sln</b>, <b>compile_commands.json</b>.<br><br><b>--error-exitcode=<exitcode></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Sets exit code when errors are found.</i> Useful for CI.<br><br><b>--platform=<platform></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies platform-specific integer sizes.</i> E.g., <b>unix64</b>, <b>win32</b>.<br><br><b>--template=<format></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Customizes the output message format.</i><br><br>


title: DESCRIPTION
content:
<b>cppcheck</b> is a static analysis tool for C and C++ code. It detects various types of errors and potential issues that compilers might miss, such as buffer overflows, memory leaks, resource leaks, uninitialized variables, unused code, and various style and performance problems.<br><br>Unlike compilers, <b>cppcheck</b> does not compile the code; instead, it parses it and applies a set of predefined rules and heuristics to identify problematic patterns. This allows it to find errors without requiring a complete build environment, making it suitable for integration into Continuous Integration (CI) pipelines or as a pre-commit hook. It aims to minimize false positives and provides customizable checks, enabling users to focus on specific categories of issues like portability or information-level warnings. It supports various C/C++ standards and can analyze entire projects or individual files.


title: CAVEATS
content:
<b>cppcheck</b> performs static analysis and does not execute the code. Therefore, it cannot find all runtime errors. It might produce false positives (warnings about non-existent issues) or false negatives (miss real bugs) depending on code complexity and configuration. For optimal results, it often requires correct include paths and preprocessor definitions to be provided, similar to a compiler. It focuses on undefined behavior and dangerous coding constructs rather than logical errors or algorithmic flaws.


title: <I>INTEGRATION WITH BUILD SYSTEMS</I>
content:
<b>cppcheck</b> can integrate with build systems like Make, CMake, and Visual Studio. For CMake projects, <b>CMAKE_EXPORT_COMPILE_COMMANDS</b> can generate a <b>compile_commands.json</b> file which <b>cppcheck</b> can use with <b>--project</b>. This simplifies providing include paths and defines.


title: <I>SUPPRESSION FILES</I>
content:
For managing warnings, <b>cppcheck</b> supports suppression files (<b>--suppress-file=&lt;file&gt;</b>). These files list warnings to ignore, allowing teams to filter out noise or acknowledge known issues without modifying the code.


title: HISTORY
content:
<b>cppcheck</b> was initially developed by Daniel Marjamäki in 2007. It was created with the goal of being a simple yet powerful tool to detect common errors in C/C++ code, emphasizing low false positive rates. Its development has been community-driven, with contributions from many developers, leading to continuous improvements in its analysis capabilities, performance, and support for newer C/C++ standards. It gained popularity due to its ease of use, open-source nature, and ability to be easily integrated into various development workflows, including CI/CD pipelines.


title: PARAMETERS
content:
<b><i>--root=&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the root directory of the project for relative paths.<br><br><b><i>--compile-commands-dir=&lt;dir&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the directory containing <i>compile_commands.json</i>.<br><br><b><i>--include=&lt;regex&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Regular expression to include files for analysis. Only matching files are processed.<br><br><b><i>--exclude=&lt;regex&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Regular expression to exclude files from analysis. Matching files are ignored.<br><br><b><i>--verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, useful for debugging parsing issues.<br><br><b><i>--print_xml</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the results in XML format, suitable for programmatic parsing.<br><br><b><i>--exit_if_unused</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit with a non-zero status code (1) if any unused code is detected, useful for CI/CD pipelines.<br><br><b><i>--version</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the <i>cppclean</i> version and exit.<br><br><b><i>--help</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show a comprehensive help message and exit.<br><br>


title: DESCRIPTION
content:
<i>cppclean</i> is a static analysis tool designed for C and C++ source code. Its primary function is to identify and report unused code elements within a project. This includes unreferenced functions, methods, variables, types, and header inclusions. By parsing source files and building a dependency graph, <i>cppclean</i> meticulously traces symbol usage, highlighting parts of the codebase that are never called, instantiated, or accessed. The aim is to help developers remove dead code, thereby reducing compilation times, improving code readability, and decreasing the overall binary size. It operates by analyzing the project's compilation units and often benefits from a <i>compile_commands.json</i> file generated by tools like CMake or Bear, which provides necessary compilation flags for accurate parsing. While <i>cppclean</i> excels at dead code detection, it is not a linter for style or a bug finder; its scope is specifically focused on identifying and facilitating the removal of unreferenced code.


title: CAVEATS
content:
<i>cppclean</i> relies heavily on the accuracy of its C++ parser; for complex projects, providing a <i>compile_commands.json</i> file (e.g., generated by CMake or Bear) is crucial for correct analysis. Without it, the tool may fail to resolve symbols due to missing include paths or compiler flags, leading to incomplete or incorrect results. It may also produce false positives for code accessed via advanced runtime mechanisms (like dynamic loading or plugin architectures) that are beyond its static analysis capabilities. <i>cppclean</i> focuses exclusively on dead code detection and should not be confused with tools for code style checking or bug finding.


title: INTEGRATION WITH COMPILATION DATABASES
content:
For accurate analysis, especially in complex C++ projects, <i>cppclean</i> strongly recommends using a compilation database (<i>compile_commands.json</i>). This file, typically generated by build systems like CMake (with <i>-DCMAKE_EXPORT_COMPILE_COMMANDS=ON</i>) or tools like Bear (<i>bear -- &lt;your_build_command&gt;</i>), provides <i>cppclean</i> with essential information about compiler flags and include paths for each source file. Using it vastly improves parsing accuracy and reduces false positives/negatives.


title: TYPICAL WORKFLOW
content:
A common workflow involves generating <i>compile_commands.json</i> first, then running <i>cppclean</i>. For example:<br><br><b>cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .</b><br><b>cppclean --compile-commands-dir=. --root=.</b><br><br>The output will list unused elements, which developers can then review and remove.


title: HISTORY
content:
<i>cppclean</i> was originally developed at Google and later open-sourced, becoming part of the <i>google/cppclean</i> project on GitHub. Its creation was motivated by the need to manage and optimize large-scale C++ codebases by systematically identifying and removing dead code. Over the years, it has been used by various organizations and individual developers to improve code hygiene, reduce build times, and decrease binary sizes in C/C++ projects.


title: SYNOPSIS
content:
<B>N/A</B> - The `cppw` command is not a standard Linux utility and therefore has <I>no defined syntax</I>. If it exists on your system, it's a custom script whose syntax would be determined by its specific implementation.


title: DESCRIPTION
content:
`cppw` (presumably short for "C++ Password" or similar) is <I>not a standard command</I> or utility found in common Linux distributions like Debian, Ubuntu, Fedora, or RHEL. Its name suggests it might be related to password manipulation or management, possibly written in C++. If you encountered `cppw`, it is highly probable that it refers to a <B>custom script</B>, a <B>user-defined alias</B>, or a <B>typo</B> for a well-known command such as `passwd` (for changing user passwords) or `chpasswd` (for batch password updates). Without a custom implementation, this command has <I>no predefined functionality</I> within the standard Linux ecosystem. Users seeking to manage passwords should refer to official utilities provided by their distribution.


title: CAVEATS
content:
The `cppw` command is <B>not standard</B>. Its presence on a system indicates a <I>custom installation</I> or <I>script</I>. Users should exercise caution and verify the origin and purpose of any non-standard executable before running it, especially one potentially related to password management. Its behavior, security implications, and dependencies would be entirely specific to its custom implementation.


title: VERIFICATION
content:
If you encounter `cppw`, check your system's <B>PATH</B> environment variable and look for executables or scripts named `cppw` in directories like `/usr/local/bin`, `~/bin`, or through `type cppw` or `which cppw` commands. This will help determine if it's an alias or a script.


title: SECURITY IMPLICATIONS
content:
Because `cppw` is non-standard, its security cannot be guaranteed. A custom password utility could potentially have vulnerabilities if not implemented carelessly. <B>Always prioritize official utilities</B> for sensitive operations like password changes.


title: HISTORY
content:
There is <I>no standard history</I> for a command named `cppw` within the mainstream Linux or Unix development. Its name does not appear in historical documentation or man pages of core utilities. Any existence of `cppw` would be a <B>recent, localized, and non-official development</B>, likely as a personal utility or part of a very specialized, non-public software distribution.


title: PARAMETERS
content:
<b><i>duration_in_seconds</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The duration, in seconds, for which the command should monitor and collect performance data. If omitted, it defaults to 1 second.<br><br><b>-d, --debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints additional debug information during execution, which can be useful for troubleshooting.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b>-V, --version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of the <b>cpufreq-aperf</b> utility and exits.<br><br>


title: DESCRIPTION
content:
The <b>cpufreq-aperf</b> command is a diagnostic tool designed to measure actual CPU frequency and core activity by utilizing the <i>APERF</i> (Actual Performance) and <i>MPERF</i> (Maximum Performance) Model Specific Registers (MSRs) available on modern x86 processors.<br>These MSRs provide a cumulative count of cycles that the CPU spent running at its current frequency (APERF) versus cycles that the CPU <i>could</i> have spent running at its maximum non-turbo frequency (MPERF). By sampling these counters over a period, <b>cpufreq-aperf</b> calculates the average operating frequency and the percentage of time the CPU was busy, effectively revealing how much of its potential performance a CPU core is actually delivering.<br>It's a valuable utility for verifying if CPU frequency scaling mechanisms are working as expected and for understanding performance bottlenecks related to CPU clock speeds. It is part of the <b>cpufrequtils</b> package.


title: CAVEATS
content:
Requires root privileges to access MSRs.<br>Relies on the availability of <i>APERF</i> and <i>MPERF</i> MSRs, which are present on most modern Intel and AMD CPUs but may not be available on all architectures or older processors.<br>The output can be challenging to interpret without an understanding of MSRs and CPU frequency scaling concepts.<br>It measures core-level performance, not overall system performance.<br>It is part of the <b>cpufrequtils</b> package; ensure this package is installed.


title: UNDERSTANDING APERF AND MPERF MSRS
content:
The command leverages two key Model Specific Registers (MSRs):<br>- <i>APERF</i> (Actual Performance Counter): Counts CPU cycles when the processor is <b>not</b> in a halted state (e.g., C0 state). This counter accumulates cycles at the actual operating frequency.<br>- <i>MPERF</i> (Maximum Performance Counter): Counts CPU cycles at the CPU's maximum non-turbo frequency (base frequency). This counter accumulates cycles as if the CPU were constantly running at its highest defined speed.<br>By comparing the difference in these counters over a time interval, <b>cpufreq-aperf</b> calculates the percentage of time the CPU was active and its average effective frequency relative to its maximum frequency.


title: OUTPUT INTERPRETATION
content:
A typical output might look like:<br><code>CPU 0: 67% busy, actual freq: 2.1 GHz, max freq: 3.2 GHz (1 second avg)</code><br>- "<b><i>X</i>% busy</b>": Represents (APERF_delta / MPERF_delta) * 100. This indicates the percentage of cycles the CPU spent executing instructions relative to the maximum possible cycles it could have executed at its base frequency.<br>- "<b>actual freq</b>": The average operating frequency of the CPU core over the measurement period. This is derived from (APERF_delta / measurement_duration).<br>- "<b>max freq</b>": The reported maximum non-turbo frequency of the CPU core, used as the reference for MPERF.


title: HISTORY
content:
The <b>cpufreq-aperf</b> utility is part of the <b>cpufrequtils</b> package, a collection of tools designed for managing and inspecting the CPU frequency scaling capabilities of Linux systems. Its development emerged alongside the increasing sophistication of dynamic CPU frequency scaling (often known as SpeedStep, PowerNow!, or Cool'n'Quiet), necessitating tools to verify the actual operating frequencies and performance states of CPU cores. <b>cpufreq-aperf</b> specifically addresses the need to validate the proper functioning of the <i>APERF</i> and <i>MPERF</i> MSRs, which are crucial for accurate performance monitoring by the kernel and other utilities.


title: PARAMETERS
content:
<b>-c <CPU></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the CPU to query. If omitted, information for all online CPUs is displayed. CPU indices are zero-based (e.g., 0, 1, 2).<br><br><b>-g</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the current CPU frequency scaling governor.<br><br><b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the current CPU frequency.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the current CPU frequency scaling driver in use (e.g., 'acpi_cpufreq', 'intel_pstate').<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the current minimum and maximum frequencies allowed by the scaling policy.<br><br><b>-m</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display all available CPU frequencies supported by the hardware and driver.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display all available CPU frequency scaling governors.<br><br><b>-u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the hardware's minimum and maximum CPU frequencies (limits).<br><br><b>-w</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display the frequency of the 'weighted' policy (less commonly used output).<br><br><b>-o</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display output in the old (legacy) format.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provide more verbose output.<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message and exit.<br><br>


title: DESCRIPTION
content:
The <b>cpufreq-info</b> command is a utility from the <i>cpufrequtils</i> package designed to provide detailed information about the CPU frequency scaling capabilities and current state of your system's processors.<br><br>It can report various aspects such as the current CPU frequency, the active scaling governor (e.g., 'ondemand', 'powersave', 'performance'), the minimum and maximum frequencies allowed by the current policy, and the available frequencies and governors supported by the hardware and kernel driver.<br><br>This tool is invaluable for system administrators and users looking to monitor power management settings, diagnose performance issues related to CPU throttling, or verify that their CPU frequency scaling is working as expected. It reads its information directly from the Linux kernel's <i>sysfs</i> interface, specifically the <i>/sys/devices/system/cpu/cpuX/cpufreq/</i> directories.


title: CAVEATS
content:
<b>cpufreq-info</b> relies heavily on the Linux kernel's <i>cpufreq</i> subsystem and appropriate CPU frequency scaling drivers (e.g., <i>acpi_cpufreq</i>, <i>intel_pstate</i>) being loaded and functional. Information accuracy and completeness depend on kernel and hardware support. While basic queries typically don't require root privileges, accessing some <i>/sys</i> filesystem entries might be restricted, potentially leading to incomplete output without sufficient permissions. Modern CPU drivers like <i>intel_pstate</i> often handle frequency scaling internally, which can make some traditional <i>cpufreq</i> mechanisms less relevant or directly controllable.


title: DEPENDENCIES
content:
The command relies on the Linux kernel's <i>cpufreq</i> subsystem being compiled in and appropriate CPU frequency scaling drivers (e.g., <i>acpi_cpufreq</i> for ACPI-compliant systems, <i>intel_pstate</i> for modern Intel CPUs) being loaded. It also requires access to the <i>/sys/devices/system/cpu/cpuX/cpufreq/</i> directory structure, which is part of the <i>sysfs</i> pseudo-filesystem.


title: USAGE EXAMPLES
content:
To get info for all CPUs: <br><code><b>cpufreq-info</b></code><br><br>To get info for CPU 0 only: <br><code><b>cpufreq-info -c 0</b></code><br><br>To see the current governor for CPU 1: <br><code><b>cpufreq-info -c 1 -g</b></code><br><br>To list all available governors on your system: <br><code><b>cpufreq-info -l</b></code>


title: HISTORY
content:
<b>cpufreq-info</b> is a key component of the <i>cpufrequtils</i> package, which emerged to provide user-space tools for interacting with the Linux kernel's CPU frequency scaling subsystem (<i>cpufreq</i>). This subsystem has been a part of the kernel for many years, evolving significantly to improve power efficiency and performance on various CPU architectures. The command's development has closely tracked the kernel's advancements in power management, offering a consistent interface to query complex scaling behaviors.


title: SYNOPSIS
content:
<b>cpufreq-set</b> [<i>options</i>]<br><b>cpufreq-set</b> <b>-c</b> <i>&lt;cpu_id&gt;</i> [<b>-d</b> <i>&lt;min_freq&gt;</i>] [<b>-u</b> <i>&lt;max_freq&gt;</i>] [<b>-g</b> <i>&lt;governor&gt;</i>] [<b>-f</b> <i>&lt;freq&gt;</i>]


title: PARAMETERS
content:
<b><b>-c</b> <i>&lt;CPU&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the CPU core to operate on. CPU IDs are zero-indexed (e.g., 0, 1, 2...). If omitted, operations might apply to all CPUs (depending on the specific option) or require a CPU ID for certain queries.<br><br><b><b>-d</b> <i>&lt;FREQ&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired minimum CPU frequency. The frequency must be specified in kilohertz (kHz). This frequency must be supported by the CPU and typically be less than or equal to the maximum frequency.<br><br><b><b>-u</b> <i>&lt;FREQ&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired maximum CPU frequency. The frequency must be specified in kilohertz (kHz). This frequency must be supported by the CPU and typically be greater than or equal to the minimum frequency.<br><br><b><b>-g</b> <i>&lt;GOVERNOR&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the CPU frequency scaling governor. Common governors include <i>ondemand</i>, <i>performance</i>, <i>powersave</i>, <i>userspace</i>, <i>conservative</i>, and <i>schedutil</i>. The chosen governor dictates the policy for dynamic frequency scaling.<br><br><b><b>-f</b> <i>&lt;FREQ&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a specific CPU frequency. This option is primarily used in conjunction with the <i>userspace</i> governor, which allows user-defined frequency settings. The frequency is specified in kilohertz (kHz).<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reports the current CPU frequency settings for the specified CPU. This option is often implicitly handled when just providing <b>-c</b> without other modification options.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays version information and exits.<br><br>


title: DESCRIPTION
content:
<i><b>cpufreq-set</b></i> is a command-line utility used to query and modify the CPU frequency scaling settings for individual CPU cores on Linux systems. It is part of the <i>cpufrequtils</i> package, which interfaces with the kernel's <i>cpufreq</i> subsystem. This command allows users to manually set the minimum and maximum frequencies a CPU core can operate at, and more importantly, to define the <i>governor</i> that dictates the CPU's frequency scaling policy.<br><br>The CPU frequency scaling mechanism is crucial for balancing performance and power consumption. By using <i><b>cpufreq-set</b></i>, administrators and users can fine-tune how their system reacts to workload demands, whether prioritizing maximum performance, optimizing for power savings, or allowing a dynamic approach. This tool is particularly useful for debugging performance issues, extending battery life on laptops, or ensuring consistent performance in specific scenarios.


title: CAVEATS
content:
Using <i><b>cpufreq-set</b></i> to modify CPU frequency settings typically requires root privileges (e.g., running with <i>sudo</i>).<br>Changes made with <i><b>cpufreq-set</b></i> are generally not persistent across system reboots. To make settings permanent, alternative methods such as systemd services, udev rules, or configuration files for specific tools (e.g., <i>cpupower</i>) must be employed.<br>Setting frequencies outside of the CPU's supported range or choosing inappropriate governors can lead to system instability, reduced performance, or increased power consumption and heat generation. Always verify supported frequencies with <i><b>cpufreq-info</b></i> before making changes.


title: CPU FREQUENCY GOVERNORS
content:
CPU frequency governors determine how the CPU dynamically adjusts its frequency. Understanding them is key to effective use of <i><b>cpufreq-set</b></i>:<br><ul><li><i><b>ondemand</b></i>: Dynamically scales frequency based on CPU load; ramps up quickly to meet demand, then scales down.</li><li><i><b>performance</b></i>: Locks the CPU at its highest possible frequency, prioritizing maximum speed regardless of load.</li><li><i><b>powersave</b></i>: Locks the CPU at its lowest possible frequency, prioritizing energy efficiency.</li><li><i><b>userspace</b></i>: Allows users or user-space programs (like <i><b>cpufreq-set -f</b></i>) to manually set the CPU frequency.</li><li><i><b>conservative</b></i>: Similar to <i>ondemand</i> but scales up and down more gradually.</li><li><i><b>schedutil</b></i>: A newer governor (Linux kernel 4.7+) that integrates with the kernel's scheduler to make more informed and efficient frequency scaling decisions. Often preferred on newer systems.


title: FREQUENCY UNITS
content:
When specifying frequencies with <b>-d</b>, <b>-u</b>, or <b>-f</b>, the values must be provided in <i>kilohertz (kHz)</i>. For example, 2.5 GHz would be 2500000 kHz.


title: PERSISTENCE ACROSS REBOOTS
content:
As mentioned in <i>caveats</i>, changes made with <i><b>cpufreq-set</b></i> are temporary. For persistent settings, consider:<br><ul><li><b>Systemd Services</b>: Create a custom systemd service that runs <i><b>cpufreq-set</b></i> commands at boot.</li><li><b>Udev Rules</b>: For some scenarios, udev rules can be used to set frequencies or governors upon device detection (e.g., on specific power events).</li><li><b>cpupower.service</b>: Many distributions provide a <i>cpupower.service</i> or similar that can be configured to apply settings persistently via its configuration files.</li></ul>


title: HISTORY
content:
<i><b>cpufreq-set</b></i> emerged as part of the <i>cpufrequtils</i> package, which was developed to provide command-line tools for interacting with the Linux kernel's <i>cpufreq</i> subsystem. This subsystem and its userspace tools were instrumental in bringing CPU frequency scaling capabilities to Linux, allowing for dynamic adjustment of clock speeds based on workload.<br><br>While still widely available and functional, <i>cpufrequtils</i> and commands like <i><b>cpufreq-set</b></i> have gradually been superseded by the more comprehensive and often integrated <i>cpupower</i> utility. <i>cpupower</i> offers a broader range of power management features beyond just frequency scaling and is typically the recommended tool on modern Linux distributions, often shipping with the kernel's source tree.


title: PARAMETERS
content:
<b><b>--raw</b>, <b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display raw hexadecimal values only.<br><br><b><b>--std</b>, <b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display standard leaves (0x0-0x1F) only.<br><br><b><b>--ext</b>, <b>-x</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display extended leaves (0x80000000-0x8000001F) only.<br><br><b><b>--level=LEVEL</b>, <b>-l LEVEL</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the maximum CPUID level to dump.<br><br><b><b>--sockets=N</b>, <b>-S N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify N CPU sockets to dump information from.<br><br><b><b>--cpu=N</b>, <b>-c N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify N logical CPUs (cores/threads) to dump information from.<br><br><b><b>--force</b>, <b>-f</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force dumping even if no CPUID driver is loaded (may not work).<br><br><b><b>--version</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display version information.<br><br><b><b>--help</b>, <b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message.<br><br><b><b>--iso</b>, <b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output ISO 9362 characters (for decoding specific fields).<br><br><b><b>--physical-cpu=N</b>, <b>-p N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump information for a specific physical CPU (socket) N.<br><br><b><b>--quiet</b>, <b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress error messages.<br><br><b><b>--decode-all</b>, <b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempt to decode all possible CPUID leaves (can be slow).<br><br><b><b>--endian=ORDER</b>, <b>-e ORDER</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set endianness for raw output (le/be for little/big endian).<br><br><b><b>--decoding-level=N</b>, <b>-d N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the decoding level for all possible leaves.<br><br><b><b>--core=N</b>, <b>-C N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump information for core N on the current socket.<br><br><b><b>--thread=N</b>, <b>-T N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dump information for thread N on the current core.<br><br><b><i>EAX_LEAF</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A hexadecimal value representing a specific CPUID leaf to query. E.g., '0x1' for processor info and feature bits.<br><br>


title: DESCRIPTION
content:
The <b>cpuid</b> command is a Linux utility designed to extract and display detailed information about the system's Central Processing Unit(s). It directly interacts with the CPU's built-in <i>CPUID</i> instruction, which provides low-level insights into the processor's architecture, features, vendor, family, model, stepping, cache topology, and supported instruction sets. This tool is invaluable for hardware diagnostics, performance tuning, and understanding the capabilities of a specific CPU. It can output either a comprehensive dump of all recognized CPUID leaves or query specific leaves by their hexadecimal EAX value. Access to the <i>/dev/cpu/N/cpuid</i> device file, provided by the <i>cpuid</i> kernel module, is typically required, often necessitating root privileges.


title: CAVEATS
content:
Access to the <i>/dev/cpu/N/cpuid</i> device file, managed by the <i>cpuid</i> kernel module, is required for most operations. This usually means the command must be run with <b>root privileges</b>.<br>The output can be highly technical and extensive, making it less suitable for casual users. The <i>--force</i> option might attempt to bypass the driver requirement but is unlikely to succeed without the underlying kernel support.


title: DIRECT CPU INTERACTION
content:
Unlike higher-level tools like <i>lscpu</i> or <i>/proc/cpuinfo</i>, which parse information gathered by the kernel at boot time, <b>cpuid</b> directly executes the <i>CPUID</i> instruction at runtime. This provides the most immediate and raw view of the processor's capabilities, making it indispensable for low-level diagnostics and development.


title: KERNEL MODULE AND PERMISSIONS
content:
For <b>cpuid</b> to function correctly, the <i>cpuid</i> kernel module must be loaded (e.g., via `modprobe cpuid`), creating device files such as <i>/dev/cpu/0/cpuid</i>. These files typically require <b>root access</b> for reading, hence why <b>cpuid</b> is often run with <i>sudo</i>.


title: HISTORY
content:
The <i>CPUID</i> instruction itself was introduced by <b>Intel</b> with the <b>Pentium</b> processor to allow software to identify CPU features dynamically. The <b>cpuid</b> Linux utility was developed by <b>H. Peter Anvin</b> to expose this instruction's output in a user-friendly command-line format. Its development parallels the increasing complexity and feature sets of modern CPUs, requiring a programmatic way to enumerate capabilities.


title: SYNOPSIS
content:
<i>cpulimit</i> <b>[OPTIONS]</b> { <b>-p</b> <i>PID</i> | <b>-e</b> <i>PROGRAM</i> | <b>-c</b> <i>COMMAND_LINE</i> }<br><i>cpulimit</i> <b>[OPTIONS]</b> <b>--</b> <i>PROGRAM</i> <b>[ARGUMENTS]</b>


title: PARAMETERS
content:
<b>-l PERCENT</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the CPU limit percentage (e.g., 50 for 50% CPU).<br><br><b>-p PID</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target process by its Process ID.<br><br><b>-e PROGRAM</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target process by its executable name.<br><br><b>-c COMMAND_LINE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Target process by its full command line.<br><br><b>-k</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Kill the process if it exceeds the limit for too long (requires <b>-l</b>).<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reset statistics after the limit has been reached, making it restart CPU calculation for a new period.<br><br><b>-z</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Exit <b>cpulimit</b> if the target process dies or is not found.<br><br><b>-b</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Run <b>cpulimit</b> in the background as a daemon.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable verbose output, showing monitoring details.<br><br><b>--</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Separator used when specifying a new program and its arguments to launch and limit.<br><br>


title: DESCRIPTION
content:
The <b>cpulimit</b> command is a utility designed to control the CPU usage of a specific process. It achieves this by sending <code>SIGSTOP</code> and <code>SIGCONT</code> signals to the target process, effectively pausing and resuming its execution to maintain its CPU consumption below a defined percentage. This is particularly useful for managing runaway processes, preventing a single application from monopolizing system resources, or ensuring fair CPU distribution among multiple tasks on a shared system. Unlike resource management through <i>cgroups</i>, <b>cpulimit</b> operates on a per-process basis and does not require kernel-level configuration. It can target processes by their Process ID (PID), executable name, or full command line, and can also launch and control new processes.


title: CAVEATS
content:
While effective for general CPU limiting, <b>cpulimit</b> has limitations.<br><br>It's not suitable for processes requiring precise real-time performance due to the nature of <code>SIGSTOP</code>/<code>SIGCONT</code> signals introducing latency. It may also struggle with very short-lived processes or those with highly bursty CPU usage patterns. As it works by pausing execution, it doesn't prevent a process from <i>requesting</i> high CPU, only from <i>consuming</i> it. For more robust and fine-grained resource control, Linux <i>cgroups</i> are generally preferred.


title: HOW IT WORKS
content:
<b>cpulimit</b> continuously monitors the CPU usage of its target process. If the process's CPU consumption exceeds the specified percentage, <b>cpulimit</b> sends a <code>SIGSTOP</code> signal to pause it. Once the usage falls below the threshold (or after a calculated pause duration), it sends a <code>SIGCONT</code> signal to resume the process. This cycle repeats to maintain the desired CPU limit.


title: COMMON USE CASES
content:
Controlling CPU-intensive tasks like video encoding, large compilation jobs, or scientific simulations to prevent system slowdowns. Limiting browser processes or Electron-based applications that might consume excessive CPU. Ensuring background batch jobs do not impact interactive user experience. Preventing runaway scripts or applications from monopolizing CPU resources.


title: HISTORY
content:
The <b>cpulimit</b> utility was developed as a straightforward alternative to more complex resource management tools like <i>cgroups</i>, focusing on an easy-to-use command-line interface for individual process CPU throttling. Its initial release was around 2007, providing a practical solution for common desktop and server scenarios where simple CPU limiting was required without extensive system configuration.


title: SYNOPSIS
content:
<b>cpupower</b> [<i>global options</i>] <i><command></i> [<i>command options</i>]<br><br>Examples:<br><b>cpupower</b> <i>--cpu 0-3</i> <b>frequency-set</b> <i>-g performance</i><br><b>cpupower</b> <b>frequency-info</b>


title: PARAMETERS
content:
<b><b>--cpu</b> <i><cpu_list></i>, <b>-c</b> <i><cpu_list></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the CPU(s) to operate on. E.g., '0' for CPU0, '0-3' for CPUs 0-3, or 'all'.<br><br><b><b>--debug</b>, <b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debugging output, showing more details about internal operations.<br><br><b><b>--version</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the cpupower utility.<br><br><b><b>frequency-set</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets CPU frequency scaling parameters like governor, min/max frequency, and boost mode.<br><br><b><b>frequency-info</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows current CPU frequency and scaling driver information, available frequencies, and governors.<br><br><b><b>idle-info</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about CPU idle states (C-states), including supported states and their latencies.<br><br><b><b>idle-set</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows modification of CPU idle state parameters, such as disabling specific C-states for a CPU.<br><br><b><b>monitor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides real-time monitoring of CPU performance counters, like frequency and C-state residency.<br><br><b><b>turbo</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables Intel Turbo Boost technology on supported CPUs.<br><br>


title: DESCRIPTION
content:
<i>cpupower</i> is a powerful command-line utility for managing and monitoring CPU frequency scaling, power saving features, and performance counters on Linux systems. It interacts directly with the kernel's <i>cpufreq</i> subsystem and other power management interfaces exposed via <i>sysfs</i>.<br><br>This tool allows users to inspect current CPU settings (like minimum/maximum frequencies, active governor, available C-states), and modify them. It's crucial for optimizing system performance, energy efficiency, or striking a balance between the two. For instance, you can set the CPU governor to "performance" for maximum speed, or "powersave" to conserve battery life. <i>cpupower</i> is the modern successor to older <i>cpufrequtils</i> tools, offering a more integrated and comprehensive set of features for CPU power management. Most of its write operations require root privileges.


title: CAVEATS
content:
<i>cpupower</i> operations, especially those that modify settings, typically require root (superuser) privileges. Incorrect usage can lead to system instability, reduced performance, or increased power consumption.<br><br>The actual functionality and available options depend heavily on the kernel's CPU frequency scaling drivers (e.g., <i>intel_pstate</i>, <i>acpi_cpufreq</i>) and underlying CPU hardware support. BIOS settings can also influence or override <i>cpupower</i> configurations.


title: CPU GOVERNORS
content:
CPU governors are kernel mechanisms that decide how to adjust CPU frequency based on system load and power policies. Common governors include <b>performance</b> (maintains max frequency), <b>powersave</b> (maintains min frequency), <b>ondemand</b> (scales based on load), and <b>schedutil</b> (kernel scheduler-driven).


title: C-STATES (IDLE STATES)
content:
C-states (or CPU idle states) are power-saving modes that a CPU can enter when it is not actively processing tasks. A higher C-state number (e.g., C3, C6, C7) indicates a deeper sleep state, consuming less power but taking longer for the CPU to wake up and resume processing. <i>cpupower</i> allows inspecting and sometimes managing these states to optimize power consumption.


title: HISTORY
content:
<i>cpupower</i> emerged as part of the <i>linux-tools</i> project, aiming to consolidate and improve CPU power management tools. It was designed to replace the collection of individual commands provided by <i>cpufrequtils</i> (such as <i>cpufreq-set</i> and <i>cpufreq-info</i>), offering a unified and more powerful interface.<br><br>Its development reflects the ongoing need for granular control over CPU performance and energy efficiency in modern Linux systems, adapting to new hardware features like Intel's P-states and C-states.


title: DESCRIPTION
content:
<i>cracklib-check</i> is a fundamental utility within the <b>CrackLib</b> library, designed to assess the robustness of user-supplied passwords. Its primary function is to help enforce strong password policies on Unix-like systems.<br>The command operates by performing a series of sophisticated checks:<br>It compares the input password against an extensive dictionary of commonly used words, names, and patterns stored in its internal databases.<br>It applies various heuristic rules to detect simple permutations, repetitions, keyboard patterns, and other easily guessable structures.<br>It also checks for passwords that are too short, too simple, or mirror user information.<br><i>cracklib-check</i> reads the password from standard input and outputs a message to standard output indicating whether the password is "OK" or providing a specific reason for its rejection (e.g., "it is based on a dictionary word," "it is too short").<br>This tool is crucial for system administrators to prevent users from selecting insecure passwords that could be easily compromised by dictionary attacks or brute-force methods, thereby enhancing overall system security.


title: CAVEATS
content:
The effectiveness of <i>cracklib-check</i> is heavily reliant on the comprehensiveness and currency of its installed dictionary files. An outdated or incomplete dictionary may allow weaker passwords to pass.<br>While it provides a crucial first line of defense, it is not a standalone solution for password security. Systems should also employ other security measures like strong encryption, rate limiting, and multi-factor authentication.<br>It checks for common weaknesses but cannot detect if a password has been previously compromised in a data breach, which requires checking against breach databases.


title: <B>INPUT AND OUTPUT</B>
content:
<i>cracklib-check</i> reads the password to be analyzed from standard input (<i>STDIN</i>), one password per line. It then prints a message to standard output (<i>STDOUT</i>). If the password is deemed strong enough, the output is typically 'OK'. Otherwise, a descriptive message indicating the reason for rejection (e.g., 'it is too short', 'it is based on a dictionary word', 'it is too simplistic/systematic') is provided.<br>The command's exit status is <b>0</b> if the password is acceptable, and <b>non-zero</b> (typically <b>1</b>) if it is rejected.


title: <B>DICTIONARY FILES</B>
content:
The effectiveness of <i>cracklib-check</i> relies on its extensive dictionary files. These files, typically located in directories such as <i>/usr/share/cracklib/</i>, contain lists of common words, names, and patterns. Key files include <i>pw_dict.pwd</i> and <i>pw_dict.pwi</i>, which are indexed dictionary databases created from larger wordlists using <i>cracklib-packer(8)</i>.


title: HISTORY
content:
<i>CrackLib</i>, including the <i>cracklib-check</i> utility, was originally developed by <b>Alec Muffett</b> in the early 1990s. Its primary motivation was to provide a robust, open-source solution for enforcing stronger password policies on Unix and Unix-like operating systems. It quickly became a standard component in many Linux distributions and other systems, widely used to prevent users from choosing easily guessable passwords, thus significantly enhancing system security practices from the user-facing side.


title: DESCRIPTION
content:
The <b>cradle</b> command is not a standard or commonly recognized utility within mainstream Linux distributions. Unlike commands such as <b>ls</b>, <b>grep</b>, or <b>tar</b>, <b>cradle</b> does not appear in common man pages, official package repositories (e.g., Debian/Ubuntu's <i>apt</i>, Fedora/RHEL's <i>dnf</i>), or widespread Linux documentation. It is highly probable that <b>cradle</b> might be: <br> 1. A typo for another command (e.g., <i>create</i>, <i>gradle</i>).<br> 2. A custom script developed for a specific environment or project.<br> 3. An internal subcommand of a larger, less common application.<br> 4. A conceptual term rather than a direct executable command. <br> Due to its unrecognized status as a standard command, detailed information regarding its syntax, options, or typical usage cannot be provided. Users are advised to verify the exact spelling or context if they encountered <b>cradle</b>.


title: CAVEATS
content:
This analysis is based on the assumption that <b>cradle</b> refers to a standard, system-wide Linux command. If it is a custom script, an alias, or a subcommand of a specific application, its behavior, syntax, and options would be entirely defined by that specific implementation, and this analysis would not apply.


title: HISTORY
content:
No documented history or significant development tracing for a standard <b>cradle</b> command within the Linux ecosystem has been found.


title: SYNOPSIS
content:
<I>cradle-elastic</I> <I>&lt;command&gt;</I> [<I>options</I>]<br><br><b>Examples of probable usage:</b><br><I>cradle-elastic</I> <b>start</b> <I>--version 7.10.2 --port 9200</I><br><I>cradle-elastic</I> <b>stop</b><br><I>cradle-elastic</I> <b>clean</b><br><I>cradle-elastic</I> <b>info</b>


title: PARAMETERS
content:
<b><b>start</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Initializes and starts a new or existing Elasticsearch instance. Often supports specifying the version and port.<br><br><b><b>stop</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Gracefully stops the running Elasticsearch instance managed by the tool.<br><br><b><b>clean</b> or <b>destroy</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shuts down the instance and removes its data directory and associated files, effectively resetting the environment.<br><br><b><b>info</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays information about the currently managed Elasticsearch instance, such as its version, port, and status.<br><br><b><b>--version &lt;version&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the exact version of Elasticsearch to download and run (e.g., <I>7.10.2</I>, <I>8.5.0</I>). Applicable to the 'start' command.<br><br><b><b>--port &lt;number&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the network port on which Elasticsearch should listen (e.g., <I>9200</I>). Applicable to the 'start' command.<br><br><b><b>--data-dir &lt;path&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a custom directory where Elasticsearch data should be stored. Applicable to the 'start' command.<br><br><b><b>--timeout &lt;duration&gt;</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies how long to wait for Elasticsearch to start up successfully.<br><br>


title: DESCRIPTION
content:
The command <I>cradle-elastic</I> is not a standard Linux command found in common distributions' core utilities or `man` pages. It is highly likely a custom script or a specialized utility, often part of a specific project's development or testing toolkit, designed to manage local instances of <I>Elasticsearch</I>. Its primary purpose is to simplify the setup, lifecycle, and teardown of Elasticsearch environments, typically for integration testing, local application development, or Continuous Integration (CI) pipelines. This kind of tool often abstracts away the complexities of downloading, configuring, starting, and stopping Elasticsearch, making it easier for developers to work with an Elasticsearch dependency without manual setup. It might be built upon existing tools like <I>go-cradle</I> or similar Go-based utilities that provide an API for controlling Elasticsearch instances programmatically. Its functionality would be entirely dependent on the specific project it belongs to.


title: CAVEATS
content:
<b><I>cradle-elastic</I> is NOT a standard Linux utility.</b> Its availability, exact syntax, and functionality are entirely dependent on the specific software project or development environment it was created for. It is not part of any common Linux distribution's default package set. Users should not expect to find this command pre-installed or universally documented via <I>man</I> pages on general-purpose Linux systems. It is primarily a development/testing tool and should not be used for production deployments of Elasticsearch.<br><br>Documentation for this command would typically be found within the specific project's README, developer documentation, or source code.


title: HISTORY
content:
The concept behind tools like <I>cradle-elastic</I> emerged with the increasing complexity of microservices and applications that depend on external services like Elasticsearch during development and testing. Manually setting up and tearing down these services for every test run or local development session became cumbersome. Tools like <I>go-cradle</I> (a known project for managing Elasticsearch instances for Go tests) inspired similar custom scripts and utilities across different programming languages and projects. While a specific history for <I>cradle-elastic</I> as a standalone, widely adopted command doesn't exist, its lineage traces back to the need for automated, ephemeral, and isolated service environments in modern software development workflows, particularly in CI/CD pipelines and local integration testing.


title: SEE ALSO
content:
docker(1) (often used for running Elasticsearch in containers), curl(1) (for interacting with Elasticsearch APIs), java(1) (Elasticsearch requires Java runtime), go(1) (if the utility is written in Go, like <I>go-cradle</I>), npm(1), yarn(1) (if part of a Node.js project's tooling)


title: SYNOPSIS
content:
<b><code>cradle</code></b> <i>[GLOBAL_OPTIONS] &lt;COMMAND&gt; [COMMAND_OPTIONS]</i><br><br>Common commands include:<br><b><code>cradle build</code></b> <i>[OPTIONS]</i><br><b><code>cradle test</code></b> <i>[OPTIONS]</i><br><b><code>cradle run</code></b> <i>[OPTIONS]</i><br><b><code>cradle shell</code></b> <i>[OPTIONS]</i><br><b><code>cradle version</code></b><br><b><code>cradle clean</code></b>


title: PARAMETERS
content:
<b><b><code>--verbose</code></b>, <b><code>-v</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enables verbose output, providing more detailed information about the execution process.</i><br><br><b><b><code>--debug</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Activates debug output, useful for troubleshooting issues by showing internal operations.</i><br><br><b><b><code>--config</code></b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies an alternative path to the <b><code>cradle.toml</code></b> configuration file, overriding the default in the project root.</i><br><br><b><b><code>--docker-host</code></b> <i>&lt;host&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Overrides the default Docker daemon host, typically specified via the <b><code>DOCKER_HOST</code></b> environment variable.</i><br><br><b><b><code>--docker-tls-verify</code></b> <i>&lt;true|false&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enables or disables TLS verification for Docker daemon connections.</i><br><br><b><b><code>--docker-cert-path</code></b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the path to Docker client certificates for TLS connections.</i><br><br><b><b><code>--help</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Displays general help information for the <b><code>cradle</code></b> command or for a specific subcommand.</i><br><br>


title: DESCRIPTION
content:
<i><br><b>Note:</b> The command 'cradle-package' is not a standard Linux command found in typical distributions. This analysis assumes the user is referring to the <b><code>cradle</code></b> command, which is the primary executable from the <b>go-cradle</b> project. The <b>go-cradle</b> project focuses on creating reproducible Go application builds and facilitating their packaging.</i><br><br><b><code>cradle</code></b> is a command-line tool designed to create reproducible Go application binaries. It achieves this by performing the entire build process within a clean, isolated Docker container, ensuring that the build environment is consistent across different machines and times. This approach eliminates issues arising from differing local development environments, such as varying Go versions, library dependencies, or system configurations. <b><code>cradle</code></b> helps ensure that the compiled binary is identical every time, which is critical for security audits, debugging, and consistent deployments in CI/CD pipelines. It is particularly useful for Go projects that require strong guarantees about their build artifacts and aims to simplify complex aspects of Go cross-compilation and dependency management for consistent packaging.


title: CAVEATS
content:
<b><code>cradle</code></b> is not a standard, pre-installed Linux command; it must be installed separately (e.g., via <b><code>go install</code></b> or pre-built binaries from its project repository).<br>It requires <b>Docker</b> to be installed and running on the host system to function, as it relies on Docker containers for isolated builds and execution environments.<br>Initial builds may require internet access to download necessary Docker images and Go modules, which can be substantial.<br>Performance can be marginally slower compared to native builds due to the overhead of Docker container management.<br>The tool's behavior is heavily influenced by the presence and content of the <b><code>cradle.toml</code></b> configuration file in the project root.


title: CONFIGURATION (<CODE>CRADLE.TOML</CODE>)
content:
Projects utilizing <b><code>cradle</code></b> are typically configured via a <b><code>cradle.toml</code></b> file located in the project's root directory. This file is pivotal for defining project-specific build parameters, including the desired Go version to use within the container, custom build flags, specific handling of dependencies, and output paths for the compiled binaries. It ensures that <b><code>cradle</code></b> can consistently reproduce the build according to the project's precise requirements, making it a central and essential component of the reproducible build process.


title: REPRODUCIBILITY PRINCIPLE
content:
The core principle behind <b><code>cradle</code></b>'s operation is the execution of Go builds within a tightly controlled and isolated Docker environment. This methodology guarantees that the build process is shielded from variations in the host system's Go toolchain, libraries, or environmental configurations. By fetching Go modules deterministically and using a fixed, specified Go toolchain version within the container, <b><code>cradle</code></b> ensures that the output binary is bit-for-bit identical across different build executions and environments, significantly enhancing reliability, verifiability, and traceability of software artifacts.


title: HISTORY
content:
The <b><code>go-cradle</code></b> project was developed to address a critical challenge in Go application development: achieving truly reproducible builds. Before tools like <b><code>cradle</code></b>, Go builds could inadvertently vary based on the host system's Go version, environment variables, and cached dependencies, leading to inconsistencies and the infamous 'works on my machine' syndrome. <b><code>cradle</code></b> emerged as a robust solution by leveraging Docker's powerful isolation capabilities to create a consistent, immutable build environment. Its usage gained traction in scenarios demanding high integrity for binaries, such as continuous integration/delivery pipelines, and projects with strict security or audit requirements, evolving to streamline complex build workflows for Go applications.


title: PARAMETERS
content:
<b>--db DB_URL</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Specifies the database connection URL. This overrides any database configuration found in the <i>cradle</i> project's settings.<br><br><b>--sql SQL_STRING</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Executes the provided SQL string directly, instead of reading from a file.<br><br><b>--dry-run</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Prints the SQL that would be executed without actually running it against the database. Useful for verification.<br><br><b>--output FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Redirects the output of the command (e.g., query results or messages) to a specified file.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>Displays a help message and exits.<br><br><b>SQL_FILE</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<br>The path to a SQL file containing statements to be executed. If not provided, and <b>--sql</b> is not used, <i>cradle-sql</i> may expect input from standard input or simply do nothing.<br><br>


title: DESCRIPTION
content:
<i>cradle-sql</i> is an executable command provided by the <i>cradle</i> project, a lightweight tool designed for managing database schema migrations. Unlike a general-purpose SQL client, <b>cradle-sql</b> is specifically intended to execute SQL scripts against a database configured within the <i>cradle</i> environment.<br><br>It allows developers to run arbitrary SQL statements or migration scripts, often as part of a development workflow or to apply a specific schema change. It can accept SQL directly via the command line or from a specified file. The command integrates with <i>cradle</i>'s database connection settings, but also allows overriding them. It's particularly useful for applying atomic SQL changes or troubleshooting migrations managed by <i>cradle</i>.


title: CAVEATS
content:
<ul><li><i>cradle-sql</i> requires a properly configured <i>cradle</i> project or an explicit database connection URL via <b>--db</b>. Without it, it cannot connect to a database.</li><li>It executes SQL directly; therefore, care must be taken with the SQL content to avoid unintended data loss or corruption, especially in production environments.</li><li>Error handling for complex SQL scripts might be basic, relying on the underlying database engine's error reporting.</li><li>This command is part of the <i>cradle</i> Python package and might not be globally available if <i>cradle</i> is installed in a virtual environment without being linked to the system's PATH.</li></ul>


title: INTEGRATION WITH CRADLE
content:
<br>While <i>cradle-sql</i> can execute arbitrary SQL, its primary context is within a <i>cradle</i> project. It often relies on the database connection information defined in the project's <i>cradle</i> configuration file, simplifying database interactions for migration-related tasks.


title: SECURITY CONSIDERATIONS
content:
<br>Executing arbitrary SQL from files or command-line arguments can pose security risks if the SQL source is untrusted or contains malicious statements. Users should ensure the integrity and safety of the SQL content before execution.


title: HISTORY
content:
The <i>cradle</i> project, and by extension <i>cradle-sql</i>, emerged as a lightweight alternative for managing database schema changes, focusing on simplicity and ease of use, particularly within Python ecosystems. Its development history is tied to the need for a less opinionated and more flexible migration tool compared to some existing, more complex frameworks. <i>cradle-sql</i> specifically serves as a utility for direct SQL execution within the <i>cradle</i> framework, complementing its migration capabilities by allowing ad-hoc or post-migration SQL operations.


title: PARAMETERS
content:
<b>&lt;base_image_ref&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The reference to the existing OCI image (e.g., <I>gcr.io/my-repo/my-image:latest</I>) to which layers will be appended.<br><br><b>&lt;layer_tarball_path&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to one or more <B>.tar.gz</B> files containing the content of the new layers. Multiple paths can be provided.<br><br><b><B>--allow-nondistributable-artifacts</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Permits pushing non-distributable layers or artifacts, which might not be supported by all registries.<br><br><b><B>--entrypoint</B> <I>strings</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a new entrypoint for the appended image. Can be provided as a comma-separated list (e.g., <I>sh,-c,exec myapp</I>).<br><br><b><B>--env</B> <I>strings</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds or updates environment variables in the image configuration (e.g., <I>MY_VAR=value</I>). Can be used multiple times.<br><br><b><B>-h</B>, <B>--help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <B>append</B> command.<br><br><b><B>--new_tag</B> <I>strings</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies new tags for the resulting appended image (e.g., <I>my-image:new-version</I>). Can be used multiple times.<br><br><b><B>--o</B> <I>strings</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides image configuration entries like <B>Entrypoint</B> or <B>Cmd</B>. For example, <I>sh,-c,echo hello</I>.<br><br><b><B>--preserve-original-entries</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When modifying image configuration, this flag ensures that original entries for fields like <B>Entrypoint</B> or <B>Cmd</B> are preserved if not explicitly overridden.<br><br><b><B>--repo</B> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target repository for the appended image if it differs from the base image's repository.<br><br><b><B>--squash</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Squashes the newly added layers into a single new layer, reducing the total number of layers in the resulting image.<br><br><b><B>--user</B> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the user or UID for the image (e.g., <I>root</I> or <I>1001</I>).<br><br><b><B>--workdir</B> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the working directory for the image (e.g., <I>/app</I>).<br><br>


title: DESCRIPTION
content:
The <B>crane append</B> command is a powerful subcommand of the <I>crane</I> utility, part of the <I>go-containerregistry</I> project. It enables users to non-destructively add one or more new layers, provided as <B>.tar.gz</B> archives, to an existing OCI (Open Container Initiative) image. This operation is performed directly against a container registry, meaning you don't need to pull the entire image or have a Docker daemon running locally. This makes it exceptionally efficient for CI/CD pipelines, allowing for quick modifications like adding configuration files, patches, or environment variables to an image without the overhead of a full rebuild. It supports pushing the modified image to a new tag or even a different repository. Beyond adding layers, it can also modify image metadata such as entrypoint, command, environment variables, user, and working directory.


title: CAVEATS
content:
The <B>crane append</B> command is not a standard Linux utility and requires the <B>crane</B> tool to be installed separately, typically via <I>go install</I> or pre-compiled binaries. It operates directly with container registries, necessitating proper authentication and permissions for both source and destination images. Layers must be provided in the OCI-compliant <B>.tar.gz</B> format. While powerful for incremental updates, misuse can lead to broken or incompatible image configurations. It is specifically designed for container image layers and not for general filesystem operations.


title: LAYER TARBALL FORMAT
content:
The layers provided to <B>crane append</B> must be in a specific <B>.tar.gz</B> format, representing a filesystem difference (a 'diff' layer). These can often be generated from a Docker container using <B>docker export</B> followed by compressing the output, or by manually creating a <B>.tar.gz</B> of the desired files.


title: TYPICAL USE CASES
content:
Common applications include adding runtime configurations (e.g., config maps, secrets), applying security patches to existing base images, updating application binaries without rebuilding the entire stack, or injecting environment variables directly into an image. It's highly favored in environments where image immutability and rapid deployment are critical.


title: HISTORY
content:
<B>crane</B> is a project from Google's <I>go-containerregistry</I> repository, designed to provide a suite of tools for direct interaction with container registries without relying on a full Docker daemon. It emerged around 2018-2019 to address challenges in CI/CD environments where fast, efficient, and daemon-less operations on container images were crucial. The <B>append</B> subcommand was developed to facilitate incremental updates and patches to existing images, avoiding the time-consuming process of rebuilding an entire image from a Dockerfile for minor changes. This makes it particularly valuable for optimizing build times and network bandwidth in automated pipelines.


title: SYNOPSIS
content:
<b>crane auth</b> <i>&lt;command&gt;</i> [<i>options</i>]<br>Available commands:<br>&nbsp;&nbsp;<b>login</b> [<i>registry</i>]<br>&nbsp;&nbsp;<b>logout</b> [<i>registry</i>]<br>&nbsp;&nbsp;<b>refresh</b><br>&nbsp;&nbsp;<b>token</b> [<i>registry</i>]


title: PARAMETERS
content:
<b>login [registry]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Authenticates to the specified container <i>registry</i>. If <i>registry</i> is omitted, it attempts to log in to default registries. Used with <b>--username</b> and <b>--password</b> or <b>--password-stdin</b>.<br><br><b>logout [registry]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deauthenticates from the specified container <i>registry</i>, removing stored credentials.<br><br><b>refresh</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to refresh existing authentication tokens for configured registries, if supported by the credential helper.<br><br><b>token [registry]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves and prints an authentication token for the specified <i>registry</i>. Can be used for programmatic access or debugging.<br><br><b>--username, -u <i>&lt;username&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username for authentication when using the <b>login</b> command.<br><br><b>--password, -p <i>&lt;password&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the password for authentication when using the <b>login</b> command.<br><i>Note: Using this flag directly in the command line is insecure; prefer <b>--password-stdin</b>.</i><br><br><b>--password-stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the password for authentication from standard input when using the <b>login</b> command. Recommended for automation and scripting to avoid exposing passwords in shell history.<br><br><b>--service <i>&lt;service&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with the <b>token</b> command to specify the service scope for the requested token.<br><br>


title: DESCRIPTION
content:
The <b>crane auth</b> command, a subcommand of the <b>crane</b> tool from the <b>go-containerregistry</b> project, provides comprehensive functionality for managing authentication credentials with OCI (Open Container Initiative) compliant container image registries. Its primary purpose is to enable secure interaction with private and public registries, allowing users to perform operations like pushing, pulling, and inspecting images.<br><br>It supports various authentication flows, including username/password-based login, and integrates with Docker's credential helper mechanisms for persistent and secure storage of tokens and refresh credentials. This command simplifies the complex process of authenticating to different registry types (e.g., Docker Hub, Google Container Registry, Amazon ECR, Azure Container Registry), abstracting away registry-specific nuances and providing a unified interface for credential management. It is an essential component for any workflow involving private container image repositories where authentication is required.


title: CAVEATS
content:
The <b>crane auth</b> command is a subcommand of the <b>crane</b> binary, not a standalone executable named 'crane-auth'. Invocation should always be prefixed with 'crane'. Its functionality heavily relies on the underlying credential helper configurations, typically found in <i>~/.docker/config.json</i>, and its behavior can vary depending on the specific registry and its supported authentication mechanisms.


title: CREDENTIAL HELPER INTEGRATION
content:
<b>crane auth</b> leverages existing Docker credential helper configurations, typically stored in <i>~/.docker/config.json</i>. This allows it to reuse credentials managed by the Docker CLI or other tools that adhere to the same standard, providing a consistent and secure authentication experience across container tools.


title: REGISTRY SUPPORT
content:
The command provides broad support for a multitude of OCI-compliant registries, including but not limited to Docker Hub, Google Container Registry (GCR), Amazon Elastic Container Registry (ECR), Azure Container Registry (ACR), Quay.io, and various self-hosted or private registries, ensuring versatility for different deployment environments.


title: HISTORY
content:
The <b>crane auth</b> command is an integral part of the <b>crane</b> tool, which emerged from Google's <b>go-containerregistry</b> project. This project was initiated to provide a pure Go library for interacting with OCI container registries, aiming to eliminate the need for a Docker daemon. The <b>auth</b> subcommand was developed to facilitate seamless and secure authentication to various registries, reflecting the evolving landscape of container image distribution and the need for flexible credential management solutions within the cloud-native ecosystem.


title: DESCRIPTION
content:
<I>The command "crane-blob" does not appear to be a standard or commonly recognized Linux command.</I><br><br>A comprehensive search across common Linux distributions, official documentation, and command databases does not yield a match for a command named "crane-blob." It is highly probable that:<br><ul><li>The command name was misremembered or misspelled.</li><li>It refers to a highly specialized, custom-built, or proprietary tool specific to a particular environment, and not part of general Linux installations.</li><li>It is a hypothetical or non-existent command.</li></ul><br>Without a verifiable existence or specific context for "crane-blob," it is not possible to provide an accurate analysis of its functionality, syntax, parameters, or history as requested for standard Linux utilities.


title: CAVEATS
content:
<I>As "crane-blob" is not a recognized standard Linux command, any information regarding its potential behavior, security implications, or resource usage would be speculative and unreliable.</I>


title: POSSIBLE MISINTERPRETATION OR RELATED CONCEPTS
content:
If you intended to refer to a command related to <B>container registries</B> (e.g., `crane` from Google's go-containerregistry, used for interacting with OCI registries) or concepts involving <B>Binary Large Objects (BLOBs)</B> in a specific context (e.g., `git-lfs` for large file storage in Git, which handles blobs), please clarify the exact command name. The term 'blob' is common in contexts like databases, version control systems (like Git's object model), and cloud storage.


title: PARAMETERS
content:
<b><I>registry</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The mandatory positional argument specifying the address of the container registry to query (e.g., <b>gcr.io</b>, <b>docker.io</b>, <b>my.private.registry:5000</b>).<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>catalog</i> command.<br><br><b>--insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows communication with insecure registries that do not use HTTPS. Use with caution.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the list of repositories in JSON format, which is useful for scripting and programmatic parsing.<br><br><b>--key <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a path to a key file, typically for signing operations (less common for <i>catalog</i>).<br><br><b>--plain-http</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the use of plain HTTP instead of HTTPS for requests, bypassing TLS/SSL. Similar to <b>--insecure</b>.<br><br><b>--token <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides an authentication token for accessing private registries (e.g., an access token from <b>gcloud auth print-access-token</b>).<br><br><b>--username <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username for basic authentication with a private registry.<br><br><b>--password <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the password for basic authentication with a private registry. It's generally recommended to avoid putting passwords directly on the command line for security reasons.<br><br>


title: DESCRIPTION
content:
<i>crane-catalog</i> is a powerful subcommand of the <I>crane</I> CLI tool, which is part of the <I>go-containerregistry</I> project. Its primary function is to query a specified container registry and retrieve a comprehensive list of all available repository names. This command is invaluable for discovery, auditing, and managing content within a registry, providing a quick overview of what images are stored. It achieves this by typically leveraging the registry's standard <i>/v2/_catalog</i> API endpoint, offering a programmatic way to explore registry contents without needing to pull individual images.


title: CAVEATS
content:
<b>API Support:</b> Not all container registries fully implement the Docker Registry HTTP API V2 <i>/v2/_catalog</i> endpoint, or they might disable it for security or performance reasons. In such cases, <i>crane-catalog</i> may fail to list repositories or return an incomplete list.<br><br><b>Authentication:</b> Accessing private registries requires proper authentication. <i>crane-catalog</i> supports various methods (username/password, tokens, Docker config files), but misconfiguration will lead to access denied errors.<br><br><b>Large Registries:</b> Querying very large registries might be slow, return truncated results if the registry has pagination limits not fully handled by the client, or if the command times out. Network conditions also play a role.


title: AUTHENTICATION METHODS
content:
<i>crane-catalog</i> can authenticate using standard Docker configuration files (e.g., <b>~/.docker/config.json</b>), environment variables like <b>DOCKER_CONFIG</b>, or explicitly via the <b>--username</b>, <b>--password</b>, and <b>--token</b> flags. For cloud-based registries like Google Container Registry (GCR) or Artifact Registry, it often leverages credentials obtained via cloud provider CLI tools (e.g., <b>gcloud</b>) that populate the Docker config.


title: REGISTRY API DEPENDENCY
content:
The command's functionality is directly dependent on the target registry's implementation of the Docker Registry HTTP API V2, specifically the <b>GET /v2/_catalog</b> endpoint. If this endpoint is not exposed or enabled by the registry, <i>crane-catalog</i> will not be able to list repositories.


title: HISTORY
content:
<i>crane</i> and its subcommands, including <i>crane-catalog</i>, are integral parts of the <I>go-containerregistry</I> project. This project, primarily developed and open-sourced by Google, provides a robust Go library and command-line tools for programmatically working with OCI (Open Container Initiative) and Docker registries. It gained popularity as a lightweight, Go-native alternative or complement to traditional container tools like <i>docker</i> and <i>podman</i> for scriptable registry interactions, making it especially useful in CI/CD pipelines and automation workflows.


title: PARAMETERS
content:
<b><b>--config-file</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternate configuration file to use instead of the default locations.<br><br><b><b>--global</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the global configuration, typically located in a system-wide directory (e.g., <i>/etc/crane/config</i>).<br><br><b><b>--user</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Operates on the user-specific configuration, typically located in the user's home directory (e.g., <i>~/.config/crane/config</i>).<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs configuration settings in JSON format, useful for scripting and programmatic access.<br><br><b><b>get</b> <i>&lt;key&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Retrieves and displays the value of a specific configuration key.<br><br><b><b>set</b> <i>&lt;key&gt;</i> <i>&lt;value&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a configuration key to a specified value. If the key does not exist, it may be created.<br><br><b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all currently configured settings and their values.<br><br><b><b>edit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Opens the active configuration file in a text editor (e.g., <i>EDITOR</i> or <i>VI</i> environment variable dependent) for manual editing.<br><br><b><b>reset</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Resets the configuration (or specific parts) to its default values, potentially deleting custom settings.<br><br>


title: DESCRIPTION
content:
The `crane` command-line tool is a powerful utility for interacting with container registries and images, often used for tasks like copying, deleting, or inspecting images without requiring a full Docker daemon. <br><br>It is important to note that the command <b>'crane-config' is NOT a standard, officially distributed command</b> as part of the `crane` tool or common Linux distributions. This analysis describes a <i>hypothetical</i> command, envisioned to manage the `crane` tool's own operational configuration (e.g., default registry, authentication settings, proxy configuration, default image formats, etc.). If it existed, it would provide a persistent way to configure `crane`'s behavior across sessions, analogous to how other CLI tools manage their settings via configuration files.


title: CAVEATS
content:
The command 'crane-config' is <b>NOT a standard, officially distributed command</b> that ships with the `crane` tool or as part of common Linux distributions. This analysis describes a <i>hypothetical</i> command based on typical patterns for managing CLI tool configurations. <br><br>The `crane` tool itself primarily relies on <i>environment variables</i> (e.g., <i>CRANE_AUTH</i>, <i>CRANE_INSECURE</i>) and specific <i>command-line flags</i> for its configuration and authentication. Do not confuse this hypothetical `crane-config` command with the existing `crane config` subcommand, which is used to inspect or update the configuration blob of a <b>container image</b>, not the `crane` tool's own operational settings.


title: TYPICAL CONFIGURATION APPROACH FOR `CRANE`
content:
Since a dedicated 'crane-config' command for the tool's operational settings does not exist, users typically configure `crane` via: <br>1.  <b>Environment Variables</b>: For authentication (e.g., `DOCKER_CONFIG` pointing to a directory with `config.json`), insecure registries (`CRANE_INSECURE_REGISTRIES`), or custom CA certificates. <br>2.  <b>Command-line Flags</b>: Many operations accept flags like `--insecure` or `--auth` for one-time configuration. <br>3.  <b>`docker/config.json`</b>: `crane` respects the `~/.docker/config.json` file for registry authentication, similar to Docker CLI. <br>Users often create shell aliases or wrapper scripts to set common environment variables or flags for persistent `crane` configurations.


title: HISTORY
content:
The `crane` tool originated from Google's `go-containerregistry` project, designed for efficient interaction with OCI image registries. Its development philosophy emphasizes simplicity and direct operations, often relying on environment variables and direct command-line arguments for dynamic configuration rather than a dedicated persistent configuration manager subcommand like 'crane-config'. Therefore, a 'crane-config' command specifically for managing the tool's own configuration has not been a primary part of its official design.


title: PARAMETERS
content:
<b><i>&lt;SOURCE&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The reference to the source image (e.g., registry.com/repo/image:tag or digest).</i><br><br><b><i>&lt;DESTINATION&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>The reference to the destination image.</i><br><br><b><b>--allow-nondistributable-blobs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Allow copying blobs that are marked as non-distributable.</i><br><br><b><b>--allow-missing-blobs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Allow copying manifests that reference missing blobs.</i><br><br><b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Allow communication with registries over HTTP or insecure HTTPS.</i><br><br><b><b>--platform</b> <i>&lt;platform&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify platform(s) (e.g., 'linux/amd64') to copy from a multi-arch manifest. Can be specified multiple times.</i><br><br><b><b>--preserve-digests</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Preserve digest references during the copy operation.</i><br><br><b><b>--preserve-tags</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Preserve all tags from the source when copying a manifest list.</i><br><br><b><b>--strict</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enforce strict OCI validation when pushing.</i><br><br><b><b>--tag</b> <i>&lt;tag&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Add an additional tag to the destination image. Can be specified multiple times.</i><br><br><b><b>--user-agent</b> <i>&lt;string&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Override the default User-Agent string sent to registries.</i><br><br>


title: DESCRIPTION
content:
<i>crane copy</i> is a powerful subcommand of the <b>crane</b> utility, designed for efficiently copying OCI (Open Container Initiative) images or manifest lists directly between two container registries. <br><br>Unlike traditional methods that might require pulling an image to a local machine and then pushing it to a new destination, <i>crane copy</i> performs the operation server-side, minimizing local disk usage and network bandwidth. It handles authentication with various registries and supports copying specific platforms from a multi-architecture image. This command is invaluable for image migration, creating backups, distributing images across different regions or accounts, and automating CI/CD workflows where direct registry-to-registry transfers are beneficial.


title: CAVEATS
content:
Using <i>crane copy</i> requires appropriate network connectivity to both the source and destination registries. Proper authentication (e.g., via <i>docker login</i> or <i>crane auth login</i>) is essential, and the user's credentials must have read access to the source and write access to the destination. Copying very large images can still be time-consuming, depending on network speeds and registry performance. Not all registries may fully support advanced OCI features, potentially leading to compatibility issues.


title: AUTHENTICATION
content:
<i>crane copy</i> leverages standard Docker credential helpers and the `~/.docker/config.json` file for authenticating with container registries, making it compatible with most existing setups.


title: USE CASES
content:
Beyond simple image migration, <i>crane copy</i> is ideal for creating registry mirrors, enabling multi-region deployments, automating image distribution in CI/CD pipelines, and creating backups of critical images across different registry providers.


title: MULTI-PLATFORM COPYING
content:
The <b>--platform</b> flag is particularly useful for selectively copying specific architectures (e.g., `linux/arm64`) from a multi-architecture image manifest without copying the entire manifest list, which helps in optimizing storage and transfer needs for specific environments.


title: HISTORY
content:
The <b>crane</b> utility, including its <i>copy</i> subcommand, was developed by <b>GoogleContainerTools</b>. It emerged as a lightweight, single-binary tool written in Go, specifically designed to simplify and streamline common container registry operations without the need for a full Docker daemon. Its development aimed to provide a more efficient solution for CI/CD pipelines and automated environments, where direct registry-to-registry transfers offer significant advantages in speed and resource consumption over traditional pull-then-push workflows.


title: SEE ALSO
content:
<b>skopeo(1)</b>: A similar command-line tool for image management, often used for copying images between registries., <b>docker(1)</b>: The main Docker CLI, which includes `docker push` for uploading local images to a registry., <b>crane</b>: The parent utility providing other subcommands for interacting with container registries (e.g., `crane pull`, `crane push`, `crane manifest`).


title: SYNOPSIS
content:
<b>crane cp</b> <I>source_image_reference</I> <I>destination_image_reference</I> [flags]<br><br>Examples:<br><b>crane cp ubuntu:latest myregistry.com/myorg/ubuntu:latest</b><br><b>crane cp myregistry.com/myrepo newregistry.com/newrepo --recursive</b><br><b>crane cp registry.example.com/app:v1 registry.example.com/app:backup --username myuser --password mypass</b>


title: PARAMETERS
content:
<b><b>--allow-nondistributable-blobs</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Permits the copying of image blobs (e.g., Windows layers) that are flagged as non-distributable by the registry.<br><br><b><b>--allow-referrers</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies any associated referrers, such as Software Bill of Materials (SBOMs) or attestations, along with the main image.<br><br><b><b>--platform string</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a target platform (e.g., <i>linux/amd64</i>) for the copied image, useful when working with multi-platform image manifests.<br><br><b><b>--recursive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies all tags and digests found within the source repository to the destination, not just the explicitly specified image reference.<br><br><b><b>--tags</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Copies all tags associated with the source repository to the destination. Similar to <b>--recursive</b> but specifically for tags.<br><br><b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows communication with registries over HTTP or bypasses TLS certificate verification for HTTPS connections. Can be specified for source (<b>--src-insecure</b>) or destination (<b>--dst-insecure</b>) separately.<br><br><b><b>--username string</b>, <b>--password string</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username and password for authentication with both source and destination private registries. Separate flags like <b>--src-username</b>/<b>--src-password</b> and <b>--dst-username</b>/<b>--dst-password</b> are also available for distinct credentials.<br><br>


title: DESCRIPTION
content:
<i>crane-cp</i> is a powerful subcommand of the <i>crane</i> tool, developed as part of the <i>go-containerregistry</i> project. It facilitates the direct and efficient copying of container images, including all their layers, configurations, and manifests, between different container registries or within the same registry. Unlike traditional methods requiring a local Docker daemon or pulling images locally, <i>crane-cp</i> operates directly against registry APIs. This makes it an ideal tool for cloud-native workflows, image migration, replication, or distribution across various environments without intermediate local storage. It supports copying by digest, tag, or recursively for entire repositories, and offers advanced options for platform-specific copying, handling insecure registries, and managing authentication.


title: CAVEATS
content:
<i>crane-cp</i> operates directly against container registries, requiring network access to both the source and destination endpoints. Proper authentication (e.g., via <i>~/.docker/config.json</i>, environment variables, or explicit <b>--username</b>/<b>--password</b> flags) is crucial for private registries. It bypasses local Docker daemons, meaning it doesn't interact with locally cached images. Users should be mindful of potential registry rate limits or storage costs, especially during large-scale image copy operations. Compatibility issues can arise if registries have different support for image manifest lists or OCI vs. Docker image formats.


title: HISTORY
content:
The <i>crane</i> tool, including its <i>cp</i> subcommand, originated from Google's <i>go-containerregistry</i> project. This initiative was launched to provide robust, programmatic, and efficient ways to interact with OCI (Open Container Initiative) registries, addressing limitations of client-side tools for registry-specific operations. <i>crane-cp</i> was a foundational feature, designed from the outset to fulfill the critical need for reliable and performant image migration and replication in cloud-native and CI/CD environments, evolving in parallel with OCI specifications and growing industry demands for direct registry manipulation.


title: PARAMETERS
content:
<b><REFERENCE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The image reference to delete. This can be a tag (e.g., <I>myregistry/myimage:mytag</I>) or a digest (e.g., <I>myregistry/myimage@sha256:digestvalue</I>).<br><br><b>--help, -h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help for the delete command.<br><br><b>--insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow insecure connections to the registry, such as HTTP or HTTPS with unverified certificates. Use with caution.<br><br><b>--platform strings</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the operating system and architecture of the image to delete (e.g., <I>linux/amd64</I>). Useful when deleting specific manifests from a multi-platform manifest list. Can be specified multiple times.<br><br><b>--registry-insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deprecated. Use <I>--insecure</I> instead. Allows insecure connections to the registry.<br><br><b>--repo string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specify the repository to delete from. If not provided, it is inferred from the image reference.<br><br>


title: DESCRIPTION
content:
The <b><I>crane delete</I></b> command is a subcommand of the <I>crane</I> CLI tool, developed by GoogleContainerTools. It provides a robust way to remove container images, manifest lists, or specific image manifests from OCI (Open Container Initiative) compliant registries such as Docker Hub, Quay.io, or Google Container Registry. <br><br>Unlike local image deletion commands (e.g., <I>docker rmi</I>), <b><I>crane delete</I></b> interacts directly with the remote registry API. This is particularly useful for automation, scripting, and managing registry storage without needing a local Docker daemon. It can delete images referenced by tag or by digest. Deleting by digest ensures the exact manifest is removed, which is crucial for managing multi-platform images or ensuring specific versions are purged. While the command initiates the deletion, the actual freeing of storage space on the registry side often depends on the registry's garbage collection process, which may not be immediate.


title: CAVEATS
content:
<b><I>Irreversible Action</I></b>: Deleting an image from a registry is typically irreversible. Once the manifest is removed, recovery is generally not possible.<br><br><b><I>Registry Garbage Collection</I></b>: While <b><I>crane delete</I></b> removes the manifest entry, the actual disk space occupied by the image layers might not be freed immediately. Registries often have a garbage collection process that runs periodically to clean up orphaned layers.<br><br><b><I>Authentication</I></b>: Proper authentication to the registry is required. <b><I>crane</I></b> often reuses credentials from <I>~/.docker/config.json</I> or environment variables, but incorrect or insufficient permissions will result in deletion failure.<br><br><b><I>Multi-platform Images</I></b>: When deleting a tag that points to a manifest list, ensure you understand if you are deleting the entire list or specific platform manifests within it. Deleting by digest is often more precise.


title: AUTHENTICATION
content:
<b><I>crane delete</I></b>, like other <I>crane</I> commands, handles registry authentication by default by checking the <I>~/.docker/config.json</I> file for stored credentials. Alternatively, credentials can be provided via environment variables (e.g., <I>CRANE_USERNAME</I>, <I>CRANE_PASSWORD</I>), or through specific cloud provider authentication mechanisms if <I>crane</I> has built-in support (e.g., GCR, ECR).


title: IMAGE REFERENCES: TAG VS. DIGEST
content:
When deleting, it's important to understand the difference between referencing an image by <I>tag</I> (e.g., <I>myimage:latest</I>) and by <I>digest</I> (e.g., <I>myimage@sha256:...</I>). Deleting by <I>tag</I> removes the tag's pointer to a manifest. The manifest itself (and its layers) might still exist if other tags or manifest lists point to it. Deleting by <I>digest</I> directly targets and removes a specific manifest. This is generally preferred for precise deletions, especially for immutable image versions or specific platform variants within a manifest list.


title: HISTORY
content:
The <I>crane</I> tool, including its <b><I>delete</I></b> subcommand, was developed by GoogleContainerTools as an open-source project. It emerged as a powerful, Go-based alternative to traditional container tooling for direct interaction with OCI registries. Its design focuses on speed, simplicity, and direct API interaction, bypassing local Docker daemons. The <b><I>delete</I></b> command has been a core functionality since early versions of <I>crane</I>, addressing the need for efficient remote image management and cleanup.


title: SEE ALSO
content:
crane pull (subcommand of crane tool), crane push (subcommand of crane tool), crane ls (subcommand of crane tool), skopeo delete (part of skopeo(1)), docker rmi (part of docker(1)), podman rmi (part of podman(1))


title: PARAMETERS
content:
<b>--format string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Go template format string to print the digest. Useful for custom output.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show help message for the digest subcommand.<br><br><b>--insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow connections to insecure registries that might use plain HTTP or have untrusted TLS certificates.<br><br><b>--platform string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target platform for multi-platform images in the format os/arch[/variant] (e.g., linux/amd64 or linux/arm/v7). If not specified, the platform of the current system might be used or an arbitrary one chosen.<br><br><b>--plain-http</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow connections to registries over plain HTTP without TLS. This is less secure and should be used with caution.<br><br><b>--repo string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional: Repository to digest from. Usually inferred from the IMAGE argument.<br><br><b>--tag string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional: Tag to digest. Usually inferred from the IMAGE argument.<br><br><b>--username string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Username for authentication to the container registry.<br><br>


title: DESCRIPTION
content:
The <I>crane digest</I> command is a subcommand of the <I>crane</I> utility, a powerful tool for interacting with container image registries. It is used to retrieve the content addressable digest (SHA256 checksum) of a specified container image. This digest uniquely identifies a specific immutable version of an image's manifest, providing a reliable way to verify the image's content and ensure supply chain integrity. Unlike image tags, which can be mutable and refer to different image layers over time, a digest always points to the exact same image content. This command is particularly useful for scripting, automation, and security-conscious workflows where precise image identification is critical for reproducibility and trust.


title: CAVEATS
content:
The 'crane-digest' command as a standalone Linux command does not exist. This analysis refers to the <I>digest</I> subcommand of the <I>crane</I> utility (<B>crane digest</B>). <I>crane</I> is a command-line tool primarily used for interacting with OCI (Open Container Initiative) container registries and images, not a general-purpose system utility.


title: AUTHENTICATION
content:
When interacting with private or authenticated registries, <I>crane digest</I> supports authentication via the <I>--username</I> flag. It can also leverage credentials cached by <I>docker login</I> in <I>~/.docker/config.json</I> for convenience, simplifying access to secured resources. For automated environments, environment variables or credential helpers might be used.


title: IMAGE SPECIFICATION
content:
The <I>IMAGE</I> argument typically includes both the repository and tag (e.g., <I>myregistry.com/myrepo/myimage:mytag</I>) or a specific digest directly (e.g., <I>myregistry.com/myrepo/myimage@sha256:...</I>). If the image is multi-platform, the <I>--platform</I> flag can be used to specify which manifest within a manifest list to digest, ensuring the correct platform-specific image content is targeted.


title: HISTORY
content:
The <I>crane</I> utility, of which <I>digest</I> is a subcommand, is part of the GoogleContainerTools project. It was developed to provide a lightweight, Go-based client for interacting with container registries without needing a full Docker or containerd daemon. Its focus is on low-level registry operations and image manipulation, making it a valuable tool for CI/CD pipelines, image analysis, and scenarios requiring direct registry interaction. The <I>digest</I> subcommand specifically addresses the need for immutable content addressing in the container ecosystem, which is crucial for reproducibility and security.


title: PARAMETERS
content:
<b><i>image-reference</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The reference to the container image in a remote registry (e.g., <I>gcr.io/google-containers/ubuntu:latest</I> or <I>myregistry.com/myimage:v1.0</I>).<br><br><b><i>output-path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The local filesystem path where the image tarball will be saved (e.g., <I>ubuntu.tar</I>). This file will contain all layers and metadata for the specified image.<br><br><b><b>-platform</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the platform for the image to pull and export (e.g., <I>linux/amd64</I>, <I>linux/arm64</I>). This is crucial for multi-architecture images to ensure the correct variant is exported.<br><br><b><b>-type</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the format of the exported tarball. Supported types are <I>docker</I> (default) and <I>oci</I>. <I>docker</I> format is compatible with <I>docker load</I>, while <I>oci</I> adheres to the Open Container Initiative image format specification.<br><br><b><b>-compress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;If this flag is present, the output tarball will be compressed using gzip, potentially reducing its file size.<br><br><b><b>-allow-nondistributable-artifacts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows pulling of non-distributable artifacts, which might be subject to license restrictions or specific registry configurations.<br><br><b><b>-insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows communication with registries over plain HTTP or disables TLS certificate validation for HTTPS connections. Use with caution as it compromises security.<br><br><b><b>-plain-http</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces communication with registries using plain HTTP, completely bypassing TLS/SSL encryption.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose logging output, providing more detailed information about the operation's progress and actions.<br><br>


title: DESCRIPTION
content:
<I>crane export</I> is a utility from the <I>go-containerregistry</I> project that allows users to pull a container image from a remote registry and save it to a local tarball.<br><br>This tarball can then be used to load the image into a container runtime (like Docker or containerd) or for offline transfer. It serves as a lightweight and fast alternative to tools like <I>docker save</I> or <I>skopeo copy</I>, especially useful in CI/CD pipelines or environments where a Docker daemon is not available or desired. It efficiently handles image layers and manifests, supporting multi-platform images and allowing the user to specify the desired output format.


title: CAVEATS
content:
Exporting very large images can consume significant disk space and network bandwidth.<br>The compatibility of the exported tarball with various container runtimes depends on the <I>--type</I> flag chosen; older runtimes might not fully support the <I>oci</I> format.<br><I>crane export</I> requires an active network connection to the image registry for the operation to succeed. It does not support exporting an image from a local cache without prior network retrieval.


title: OUTPUT TARBALL TYPES
content:
The <I>--type</I> flag offers flexibility in the format of the exported tarball:<br>• <b>docker</b>: This is the default type and generates a tarball compatible with the <I>docker load</I> command. It often contains multiple image manifests and layers, making it suitable for direct import into a Docker daemon.<br>• <b>oci</b>: This type generates a tarball that adheres to the Open Container Initiative (OCI) image format specification. OCI-compliant tarballs are designed for broader compatibility with modern container runtimes and tools that support OCI standards, offering a more standardized and portable format.


title: MULTI-PLATFORM IMAGE HANDLING
content:
For images that support multiple architectures (e.g., <I>linux/amd64</I>, <I>linux/arm64</I>), using the <I>--platform</I> flag is essential. Without it, <I>crane</I> might select a default platform based on the system it's running on, or an arbitrary choice from the manifest list. Explicitly specifying the platform ensures that the exact architecture you intend to export is pulled and saved into the tarball.


title: HISTORY
content:
The <I>crane</I> utility is an integral part of the <I>go-containerregistry</I> project, an open-source collection of Go libraries and tools developed by Google. Conceived to provide a lightweight, fast, and daemonless approach to interacting with OCI-compliant container registries, <I>crane</I> (and thus <I>crane export</I>) emerged as a preferred tool in CI/CD pipelines, scripting, and environments where direct Docker daemon dependency is undesirable. Its development emphasizes efficiency and programmatic control over container images and registries.


title: SYNOPSIS
content:
<b>crane</b> [<i>GLOBAL_OPTIONS</i>] <b>flatten</b> <I>SOURCE_IMAGE_REFERENCE</I> <I>DESTINATION_IMAGE_REFERENCE</I>


title: PARAMETERS
content:
<b><I>SOURCE_IMAGE_REFERENCE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The reference to the source container image (e.g., <code>myregistry/myimage:latest</code>) to be flattened.<br><br><b><I>DESTINATION_IMAGE_REFERENCE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The reference where the flattened image will be pushed (e.g., <code>myregistry/myimage:flattened</code>).<br><br><b><b>--allow-nondistributable-artifacts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows pushing non-distributable layers, such as <code>scratch</code>-based layers. Defaults to <code>false</code>.<br><br><b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Permits insecure HTTP requests to registries, bypassing TLS certificate verification. Use with caution. Defaults to <code>false</code>.<br><br><b><b>--platform</b>=<i><OS>/<ARCH></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target platform (e.g., <code>linux/amd64</code>, <code>linux/arm64</code>) for the image if it's a multi-platform image. Defaults to <code>linux/amd64</code>.<br><br><b><b>--registry-option</b>=<i><KEY>=<VALUE></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides registry-specific options in <code>key=value</code> format (e.g., <code>gcr.io=allow-nondistributable-artifacts</code>).<br><br><b><b>--user-agent</b>=<i><STRING></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the User-Agent string for registry requests.<br><br>


title: DESCRIPTION
content:
The <b>crane flatten</b> command, part of the <i>go-containerregistry</i> project's <br><code>crane</code> CLI tool, is designed to optimize container images by consolidating <br>all their distinct layers into a single, cohesive layer. <br><br>Container images are typically built as a series of read-only layers, <br>where each layer represents a change from the previous one. While this <br>layered approach offers efficient storage and caching during image builds, <br>it can sometimes lead to larger-than-necessary images, especially if files <br>are added and then removed in subsequent layers. <br><br><b>crane flatten</b> addresses this by effectively 'squashing' all these <br>intermediate layers down to a single filesystem state. This process <br>can result in a smaller final image size, potentially reducing download <br>times and attack surface by eliminating unnecessary historical data or <br>intermediate build artifacts. It's particularly useful for creating <br>minimal base images (like 'scratch' based images) or for preparing images <br>for environments where a flattened structure is preferred for security or <br>simplicity reasons.


title: CAVEATS
content:
<ul><li><b>Loss of History:</b> Flattening an image removes the ability to inspect individual layers, making it harder to understand the image's build history or debug issues related to specific changes.</li><li><b>Debugging Challenges:</b> Without distinct layers, debugging an image that encounters issues can be more complex, as you lose the granular context of how the filesystem evolved.</li><li><b>Potential Size Increase:</b> In rare cases, if a layer adds a large file and a subsequent layer removes it, flattening might result in a larger image size compared to the original layered image, as the 'removed' data might still contribute to the single flattened layer's size if not properly optimized during the squashing process.</li><li><b>Cache Invalidation:</b> A flattened image will not benefit from Docker/container runtime layer caching, as there's only one layer to cache.</li></ul>


title: USE CASES
content:
<b>crane flatten</b> is commonly used for:<br><ul><li>Creating truly minimal images (e.g., from <code>FROM scratch</code>) by removing all <br>intermediate build artifacts and tools from the final image.</li><li>Reducing the attack surface of an image by eliminating potentially vulnerable <br>files that were only temporarily present in intermediate layers.</li><li>Simplifying image structure for specific deployment scenarios or custom <br>container runtimes that might prefer single-layer images.</li></ul>


title: LAYERED VS. FLATTENED IMAGES
content:
Traditional container images are built as a union filesystem of multiple layers. <br>Each <i>ADD</i>, <i>COPY</i>, <i>RUN</i> instruction in a Dockerfile often creates a new layer. <br>This allows for efficient storage (sharing common base layers) and faster <br>builds (caching unchanged layers). A flattened image, on the other hand, <br>represents only the final state of the filesystem, as if all changes from <br>all layers were applied to a single base layer.


title: HISTORY
content:
The <b>crane</b> tool is part of the <i>go-containerregistry</i> project, an open-source <br>library and command-line utility set developed by Google. It provides <br>efficient, low-level access and manipulation capabilities for container <br>images and registries, implemented purely in Go. The <b>flatten</b> subcommand <br>was introduced to address common needs in container image optimization, <br>especially in cloud-native build pipelines and environments where image size <br>and simplicity are critical considerations. Its development reflects the <br>ongoing evolution of best practices for container image management.


title: SYNOPSIS
content:
`crane-index` <I>does not have a standard synopsis</I> as a standalone command.<br>If referring to the <B>crane index</B> subcommand group, typical usage patterns are:<br><b>crane index create</b> [OPTIONS] <I>MANIFEST...</I><br><b>crane index append</b> [OPTIONS] <I>INDEX</I> <I>MANIFEST...</I><br><b>crane index merge</b> [OPTIONS] <I>MANIFEST...</I><br><b>crane index delete</b> [OPTIONS] <I>INDEX</I> <I>MANIFEST...</I>


title: PARAMETERS
content:
<b><I>Note</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;These parameters apply to various <B>crane index</B> subcommands, not a standalone `crane-index` command.<br><br><b>`--help`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show help for the specific</I> `crane index` <I>subcommand.</I><br><br><b>`--platform=<os>/<arch>`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the platform for the manifest being added or manipulated (e.g., `linux/amd64`). Used with `create` to indicate target platform, or with `append`/`merge` to associate a manifest with a specific platform.</I><br><br><b>`--type=<type>`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specify the type of index or manifest to create (e.g., `oci`, `docker`).</I><br><br><b>`--tag=<tag>`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Tag the resulting index after creation, append, or merge operations to a specific registry location (e.g., `myregistry/myimage:newindex`).</I><br><br><b>`--output=<path>`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Write the output (e.g., the resulting manifest digest or index content) to a specified file path instead of standard output.</I><br><br><b>`--insecure`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Allow communication with registries over insecure (HTTP) connections or without certificate validation. <B>Use with caution in production environments.</B></I><br><br><b>`--username=<user>`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Provide a username for authenticating with the container registry. Often used in conjunction with `--password` or `CRANE_PASSWORD` environment variable.</I><br><br><b>`--password=<pass>`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Provide a password for authenticating with the container registry. It is generally safer to use the `CRANE_PASSWORD` environment variable to avoid exposing credentials in shell history.</I><br><br><b>`--json`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Output results in JSON format, often for programmatic parsing.</I><br><br><b>`--repo=<repo>`</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>For some subcommands, specifies the target repository for an operation.</I><br><br>


title: DESCRIPTION
content:
`crane-index` is <I>not</I> a commonly recognized or standard standalone command within typical Linux distributions or popular command-line utilities. Its naming suggests a potential relation to <B>crane</B>, a powerful command-line tool for interacting with container registries (like Docker Hub, GCR, Quay.io) developed by Google as part of the `go-containerregistry` project.<br><br>It is highly probable that the query for `crane-index` refers to the `index` <I>subcommand group</I> of the <B>crane</B> tool. The `crane index` subcommand group provides operations for manipulating OCI (Open Container Initiative) image indexes, which are manifest lists that refer to multiple image manifests (e.g., for different architectures or OS types). These operations include:<br><I>Creating</I> new image indexes.<br><I>Appending</I> images or manifests to an existing index.<br><I>Merging</I> multiple indexes or manifests into a single index.<br><I>Deleting</I> specific manifests from an index or entire indexes.


title: CAVEATS
content:
The command `crane-index` is <B>not</B> a standard or widely distributed Linux utility. Information provided here assumes it refers to the `index` subcommand group of the <B>crane</B> tool. If you encountered `crane-index` in a specific context (e.g., a custom build system, a specific project), it might be a custom script or a niche application designed for a particular workflow.


title: UNDERSTANDING OCI IMAGE INDEXES
content:
OCI Image Indexes are crucial for supporting multi-platform images. Instead of creating separate image tags for different architectures (e.g., `myimage:latest-amd64`, `myimage:latest-arm64`), an index allows a single tag (`myimage:latest`) to point to a list of manifests, each for a different architecture. The <B>crane index</B> subcommands facilitate the creation and modification of these indexes, making <B>crane</B> a valuable tool for building and distributing multi-architecture container images effectively.


title: INSTALLATION OF <B>CRANE</B>
content:
Since `crane-index` is likely a misnomer for `crane index`, users should install the <B>crane</B> tool. It can typically be installed by downloading pre-compiled binaries from its GitHub releases page (`github.com/google/go-containerregistry/releases`), or via package managers like Homebrew on macOS and Linux (`brew install crane`), or by compiling from source using Go (`go install github.com/google/go-containerregistry/cmd/crane@latest`). Ensure you have Go installed and configured if choosing the `go install` method.


title: HISTORY
content:
There is <I>no documented history</I> for a standalone `crane-index` command. The <B>crane</B> tool, which includes the `index` subcommand group, was developed by Google as part of the `go-containerregistry` project. Its development began around 2018, focusing on efficient and reliable interaction with OCI registries, and it continues to be actively maintained, evolving with containerization standards.


title: PARAMETERS
content:
<b>TARGET_INDEX_REF</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The reference (e.g., registry/repo:tag or registry/repo@sha256:digest) of the OCI image index to which manifests will be appended. If this index does not exist, <B>crane</B> will initialize it as a new OCI image index.<br><br><b>IMAGE_TO_APPEND_REF</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more references (e.g., registry/repo:tag or registry/repo@sha256:digest) of the image manifests or other OCI image indexes to append to the <I>TARGET_INDEX_REF</I>.<br><br><b>--platform <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the platform (e.g., <I>os/arch[/variant]</I>, like <I>linux/amd64</I> or <I>windows/arm64/v7</I>) for the <I>IMAGE_TO_APPEND_REF</I> being added. This is crucial for properly describing entries within a multi-architecture index.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the resulting OCI index manifest to standard output in JSON format after the append operation is complete.<br><br><b>--pretty</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used in conjunction with <B>--json</B> to pretty-print the JSON output, making it more human-readable.<br><br><b>--sort</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts the appended manifests within the OCI index by their platform descriptors. This helps maintain a consistent order in the manifest list.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <B>crane index append</B> command.<br><br><b>--username <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Username for authenticating with the image registry.<br><br><b>--password <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Password for authenticating with the image registry.<br><br><b>--insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow connecting to insecure registries (those not using HTTPS or with self-signed certificates). Use with caution.<br><br><b>--config <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to a <I>config.json</I> file containing registry credentials, typically <I>~/.docker/config.json</I>.<br><br>


title: DESCRIPTION
content:
The <B>crane index append</B> command is a sub-command of the <B>crane</B> tool, which is a powerful, Go-based command-line utility developed by GoogleContainerTools for interacting with OCI (Open Container Initiative) compatible image registries. It provides low-level access to OCI manifests and blobs, making it ideal for automation and scripting where direct registry manipulation is required.<br><br>Specifically, <B>crane index append</B> is used to add one or more image manifests or other OCI index manifests to an existing OCI image index. An OCI image index is a list of image manifests, often used to create multi-architecture images (e.g., a single tag pointing to different images for Linux/amd64, Linux/arm64, Windows, etc.). If the specified target index does not exist, <B>crane</B> will typically create a new OCI image index and then append the provided manifests to it.<br><br>This command is invaluable in CI/CD pipelines for managing container images, especially when building and publishing multi-platform images from separate builds. It allows for the incremental construction or modification of complex image indexes directly on the registry without requiring a local Docker daemon or extensive image pulling.


title: CAVEATS
content:
Network connectivity to the target image registries is required for this command to function. Proper authentication credentials (username/password or config file) may be necessary to pull or push manifests, especially to private registries. When appending to an existing index, ensure that the <I>TARGET_INDEX_REF</I> truly refers to an OCI image index, as appending to a regular image manifest might lead to unexpected behavior or errors.


title: OCI IMAGE INDEX EXPLAINED
content:
An OCI Image Index (also known as a manifest list) is a standard OCI artifact that references multiple image manifests. It allows a single tag (e.g., <I>my-app:latest</I>) to resolve to different image manifests based on characteristics like operating system and architecture. This is fundamental for distributing multi-platform images, where users can pull the same tag and automatically get the correct image for their environment.


title: COMMON USE CASES
content:
<B>crane index append</B> is frequently used for:<br><I>1. Multi-Architecture Image Creation:</I> After building distinct images for different architectures (e.g., <I>my-app:linux-amd64</I>, <I>my-app:linux-arm64</I>), these can be combined into a single multi-arch index (<I>my-app:latest</I>).<br><I>2. Bundling Related Images:</I> Grouping different versions or variants of an application under one index for easier management.<br><I>3. CI/CD Pipelines:</I> Automating the process of updating or creating new image indexes as part of a continuous integration and delivery workflow.


title: HISTORY
content:
<B>crane</B> was developed by the GoogleContainerTools team to provide a lightweight, Go-based alternative to the <B>docker</B> CLI for interacting directly with OCI (Open Container Initiative) image registries. It emerged from the need for simpler, scriptable tooling for registry operations without requiring a full Docker daemon. <B>crane index append</B> is a core part of its functionality, enabling advanced manipulation of OCI image indexes, especially critical for multi-architecture image workflows in modern container ecosystems. Its development is open-source and actively maintained on GitHub.


title: SEE ALSO
content:
crane(1), crane index create(1), crane index delete(1), crane index modify(1), crane push(1), docker(1), oras(1)


title: SYNOPSIS
content:
<b>crane index filter</b> <I>SOURCE_INDEX</I> [<b>--output</b> <I>PATH</I>] [<b>--os</b> <I>OS</I>] [<b>--arch</b> <I>ARCH</I>] [<b>--variant</b> <I>VARIANT</I>] [<b>--platform</b> <I>PLATFORM</I>] [<b>--features</b> <I>FEATURES</I>] [<b>--os-version</b> <I>VERSION</I>] [<b>--os-features</b> <I>OS_FEATURES</I>]


title: PARAMETERS
content:
<b><I>SOURCE_INDEX</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The reference to the source OCI image index (e.g., <I>gcr.io/my-repo/my-image:latest</I>) to be filtered.<br><br><b><b>--output</b>, <b>-o</b> <I>PATH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path where the filtered OCI image index should be written. If not provided, the output is typically written to standard output.<br><br><b><b>--os</b> <I>OS</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters manifests by the specified operating system (e.g., <I>linux</I>, <I>windows</I>).<br><br><b><b>--arch</b> <I>ARCH</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters manifests by the specified architecture (e.g., <I>amd64</I>, <I>arm64</I>, <I>ppc64le</I>).<br><br><b><b>--variant</b> <I>VARIANT</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters manifests by the specified architecture variant (e.g., <I>v7</I>, <I>v8</I> for ARM architectures).<br><br><b><b>--platform</b> <I>PLATFORM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters manifests by a combined platform string (e.g., <I>linux/arm64/v8</I> or <I>windows/amd64</I>). This flag can be used multiple times to include multiple platforms.<br><br><b><b>--features</b> <I>FEATURES</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters manifests by additional image features.<br><br><b><b>--os-version</b> <I>VERSION</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters manifests by the operating system version.<br><br><b><b>--os-features</b> <I>OS_FEATURES</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters manifests by specific operating system features.<br><br><b><b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the `index filter` subcommand.<br><br>


title: DESCRIPTION
content:
The `crane-index-filter` command is a subcommand of the `crane` utility, specifically invoked as <I>crane index filter</I>. It is a powerful tool designed for manipulating OCI (Open Container Initiative) image indexes, also known as manifest lists. An OCI image index is a collection of references to image manifests, often used for multi-platform images (e.g., images supporting different CPU architectures like <I>amd64</I>, <I>arm64</I>, or operating systems like <I>linux</I>, <I>windows</I>).<br><br>This command allows users to create a new, filtered image index from an existing one, by specifying criteria such as operating system, architecture, or architecture variant. This is particularly useful in scenarios where you need to extract a specific platform's image from a fat manifest for deployment, testing, or optimized distribution, without pulling the entire multi-platform artifact. The filtered index will only contain references to the manifests that match the specified criteria, making it easier to manage and deploy container images for specific environments.


title: CAVEATS
content:
The command `crane-index-filter` is not a standalone executable found in typical Linux distributions. It is part of the `crane` utility, which must be installed separately. The correct invocation is <I>crane index filter</I>. Users must be familiar with OCI image specifications, especially concerning manifest lists, to effectively use this command.<br><br>The filtering operation creates a <I>new</I> index; it does not modify the original source index in place. For pushing the filtered index to a registry, additional <I>crane</I> commands (like <I>crane push</I>) are required.


title: UNDERSTANDING OCI IMAGE INDEXES
content:
An OCI Image Index (often referred to as a 'manifest list' or 'fat manifest') is a standard way to group multiple image manifests, typically for different platforms (OS/architecture combinations), under a single tag. This allows tools like Docker or Kubernetes to automatically select the correct image for the host platform. <I>crane index filter</I> provides a mechanism to manipulate these indexes, enabling precise control over which platform variants are included or excluded from a new index.


title: COMMON USE CASES
content:
This command is invaluable in CI/CD pipelines for:<br>1. <B>Optimized Image Distribution</B>: Creating a smaller, platform-specific image index to serve to a specific environment, reducing unnecessary downloads.<br>2. <B>Testing Specific Platforms</B>: Isolating a particular platform's image for focused testing.<br>3. <B>Image Curating</B>: Removing unwanted or unsupported platform variants from a publicly distributed multi-platform image.


title: HISTORY
content:
The `crane` utility is part of the `go-containerregistry` project (<I>github.com/google/go-containerregistry</I>), initially developed by Google and later open-sourced. It provides a set of libraries and CLIs for working with OCI images and registries. The `index filter` subcommand was introduced as OCI image indexes gained prominence for distributing multi-platform container images, enabling users to efficiently select or curate specific platform variants without manual parsing of manifest lists. Its development reflects the growing need for robust, programmatic control over container image lifecycle management.


title: PARAMETERS
content:
<b><i>repository</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>name of the image repository</b> (e.g., gcr.io/google-containers/pause) from which to list tags. This argument is <i>required</i>.<br><br><b><b>--config</b> <i>path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to a <b>crane configuration file</b>, typically used for authentication credentials. If not provided, crane will look for standard Docker configuration files.<br><br><b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows connecting to registries over <b>HTTP</b> or with <b>self-signed certificates</b>, bypassing TLS verification. Use with caution.<br><br><b><b>--json</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the list of tags in <b>JSON format</b>, which is useful for programmatic consumption. By default, tags are listed one per line.<br><br><b><b>--verbose</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables <b>verbose logging</b>, displaying more detailed information about the operation, including HTTP requests and responses.<br><br>


title: DESCRIPTION
content:
The `crane-ls` command is a subcommand of the `crane` utility, which is part of the `go-containerregistry` project developed by Google. `crane` is a command-line tool designed for interacting with container registries <i>without requiring a Docker daemon</i>.<br><br>The `ls` subcommand specifically allows users to list <b>all tags</b> associated with a given image repository in a remote container registry. This is useful for inspecting the contents of a registry, discovering available image versions, or verifying successful image pushes. It provides a lightweight alternative to complex Docker operations for simply inspecting available tags.<br><br>It is particularly useful in CI/CD pipelines or minimalistic environments where a full Docker daemon might be overkill or unavailable. `crane-ls` supports various registry authentication methods and works with most <i>OCI-compliant registries</i>.


title: CAVEATS
content:
`crane-ls` requires <b>network access</b> to the target container registry.<br>For <b>private registries</b>, appropriate authentication (e.g., via `docker login` or `--config`) is necessary.<br>Public registries might enforce <b>rate limiting</b>, potentially affecting large or frequent requests.<br>Listing tags for repositories with a <b>very large number of tags</b> (thousands) might be slow or hit API limits.


title: REGISTRY AUTHENTICATION
content:
By default, `crane` attempts to use existing credentials found in the standard <b>Docker configuration file</b> (typically `~/.docker/config.json`). If this file does not exist or does not contain the necessary credentials, you might need to use `docker login`, `crane auth login`, or provide a custom configuration file via the <b>`--config`</b> flag to authenticate with private registries.


title: OCI COMPLIANCE
content:
`crane` is built to be compatible with <b>OCI (Open Container Initiative) compliant registries</b>. This broad compatibility ensures it works seamlessly with popular registry services like Docker Hub, Google Container Registry (GCR), Amazon Elastic Container Registry (ECR), Quay.io, Azure Container Registry (ACR), and many others.


title: HISTORY
content:
`crane` is an open-source project developed by <b>Google</b> as part of the `go-containerregistry` suite of tools and libraries. It was designed to provide a lightweight and daemonless method for interacting with <i>OCI-compliant container registries</i>. The `ls` subcommand has been a fundamental part of `crane` since its early development, offering a simple way to inspect registry contents. It has continuously evolved alongside OCI standards and registry capabilities.


title: SYNOPSIS
content:
<b>crane manifest</b> <I>COMMAND</I> [<i>OPTIONS</i>] <I>ARGUMENTS</I><br><br><i>Available Commands:</i><br><b>  create</b> <I>REFERENCE</I> <I>IMAGE...</I> [<i>OPTIONS</i>]<br><b>  add</b> <I>MANIFEST_LIST_REF</I> <I>IMAGE_REF</I> [<i>OPTIONS</i>]<br><b>  rm</b> <I>MANIFEST_LIST_REF</I> <I>IMAGE_REF</I> [<i>OPTIONS</i>]<br><b>  list</b> <I>REFERENCE</I> [<i>OPTIONS</i>]<br><b>  annotate</b> <I>MANIFEST_LIST_REF</I> <I>IMAGE_DIGEST</I> [<i>OPTIONS</i>]


title: PARAMETERS
content:
<b>--output, -o</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a local file path to write the manifest list to, instead of pushing it to a registry. Useful for inspection or further processing.<br><br><b>--platform</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target platform (e.g., 'linux/amd64', 'windows/arm64') for an image when adding it to or annotating it within a manifest list. Used to explicitly declare the architecture and OS of an entry.<br><br><b>--annotation <key>=<value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Add one or more key-value annotations to an image entry in a manifest list. This option can be used multiple times to add multiple annotations. Common annotations include 'org.opencontainers.image.url', 'org.opencontainers.image.source', etc.<br><br><b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For the 'list' subcommand, output the manifest list contents in JSON format, facilitating programmatic parsing and scripting.<br><br><b>--tag <tag-name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For the 'create' subcommand, specify the tag name for the newly created manifest list in the registry.<br><br><b>--digest-file <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the digest of the pushed manifest list to the specified file. Useful for capturing the exact reference for later use.<br><br>


title: DESCRIPTION
content:
<i>crane-manifest</i> is a subcommand of the <b>crane</b> tool, part of the <i>go-containerregistry</i> project. It is specifically designed to interact with and manipulate OCI image indexes (also known as Docker manifest lists or multi-architecture manifests). These lists are crucial for distributing container images that support multiple CPU architectures (e.g., <i>amd64</i>, <i>arm64</i>), operating systems (e.g., Linux, Windows), or other variants under a single tag.<br><br>The command allows users to create new manifest lists from a set of existing images, add or remove images from an existing list, inspect the contents of a list, and annotate individual image entries within a list with platform-specific metadata or other properties. It provides a lightweight, daemon-less way to manage these complex image structures directly with container registries, making it a valuable tool for CI/CD pipelines, cross-platform image builds, and general registry administration.


title: CAVEATS
content:
Using <i>crane-manifest</i> requires direct access to and appropriate authentication for the target container registry. As it directly manipulates registry contents, caution is advised, especially in production environments. A basic understanding of OCI image index and Docker V2 Schema 2 manifest list specifications is beneficial for advanced usage and troubleshooting.


title: KEY USE CASES
content:
<b>Key Use Cases</b>:<br><i>crane-manifest</i> is invaluable for:<br>- Creating and managing multi-architecture container images (e.g., providing a single tag that resolves to different images for <i>linux/amd64</i>, <i>linux/arm64</i>, <i>windows/amd64</i>, etc.).<br>- Automating the promotion and deployment of container images in continuous integration and continuous delivery (CI/CD) workflows.<br>- Inspecting and verifying the structure and contents of manifest lists directly within container registries.<br>- Facilitating the creation and management of custom or private image variants under a unified registry entry.


title: SCRIPTING AND AUTOMATION
content:
Due to its command-line interface and predictable output, <i>crane-manifest</i> is highly amenable to scripting. Its daemon-less operation makes it an ideal tool for integration into automated build systems, shell scripts, and other orchestration environments where direct registry interaction is required without the overhead of a full container engine.


title: HISTORY
content:
The <i>crane</i> tool, and consequently <i>crane-manifest</i>, is an integral part of the <i>go-containerregistry</i> project, primarily developed by Google. This project was initiated to provide robust Go libraries and command-line utilities for seamless interaction with OCI (Open Container Initiative) registries and container images, without the necessity of a Docker daemon. It gained rapid adoption due to its efficiency, simplicity, and excellent suitability for integration into CI/CD pipelines and automation scripts, offering a lightweight yet powerful alternative for managing container images compared to more traditional tools. <i>crane-manifest</i> specifically addresses the critical and growing need for comprehensive multi-architecture image support within this ecosystem.


title: PARAMETERS
content:
<b>--add-layer <path/to/tarball></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a new layer to the image from a local tarball (e.g., 'crane save' output or a custom tarball).<br><br><b>--cmd '["cmd","arg"]'</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the default command (CMD) for the image. Must be a JSON array string.<br><br><b>--config-file <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies multiple mutations from a YAML or JSON configuration file. This is a powerful way to define complex changes.<br><br><b>--delete-layer <digest></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Deletes a layer from the image identified by its digest (e.g., 'sha256:...').<br><br><b>--entrypoint '["cmd","arg"]'</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the entrypoint for the image. Must be a JSON array string.<br><br><b>--env <key=value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or overrides an environment variable in the image configuration. Can be specified multiple times.<br><br><b>--label <key=value></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets or overrides an image label. Can be specified multiple times.<br><br><b>--new-tag <tag></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a new tag to the mutated image. The mutated image is pushed to the original repository with this new tag.<br><br><b>--os <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the operating system (e.g., 'linux', 'windows') in the image configuration.<br><br><b>--os-feature <feature></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets an OS feature (e.g., 'windows.servercore'). Can be specified multiple times.<br><br><b>--os-version <version></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the OS version string in the image configuration.<br><br><b>--output <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the mutated image to a local OCI layout path instead of pushing it back to a registry.<br><br><b>--platform <platform></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When mutating a multi-platform (manifest list) image, specifies the target platform (e.g., 'linux/amd64', 'windows/arm64') to mutate.<br><br><b>--user <name_or_uid></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the user or UID/GID that the container will run as.<br><br><b>--working-dir <path></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the working directory for the container.<br><br>


title: DESCRIPTION
content:
The <b>crane mutate</b> command, part of the <i>go-containerregistry (crane)</i> utility, allows for efficient modification of container image metadata and content directly within a container registry without requiring a full image pull or a local Docker daemon. It enables users to alter various aspects of an image, such as environment variables, labels, entrypoints, working directories, or even add/delete layers. This capability is particularly valuable in CI/CD pipelines for post-processing images, re-tagging, or applying patches without incurring the overhead of rebuilding or transferring large image blobs locally. It manipulates the image manifest and configuration, then pushes the updated manifest back to the registry, often resulting in a new image digest.


title: CAVEATS
content:
The <b>crane mutate</b> command requires direct network access to the container registry and appropriate authentication credentials. When mutating an image, a new manifest is typically pushed, potentially with a new digest. If you specify <i>--new-tag</i>, it will overwrite any existing image at that tag. Exercise caution, especially in production environments, as unintended changes or tag overwrites can occur. It's crucial to understand that 'mutate' doesn't *change* the existing image in-place, but rather creates a modified *version* of it.


title: INSTALLATION
content:
<b>crane</b> is a standalone Go binary. It can be installed by downloading pre-built releases from its GitHub repository (<i>github.com/google/go-containerregistry/pkg/crane</i>) or via <i>go install</i> if you have the Go toolchain configured.


title: AUTHENTICATION
content:
<b>crane mutate</b> uses standard OCI registry authentication mechanisms, typically reading credentials from your Docker configuration file (<i>~/.docker/config.json</i>) or environment variables (e.g., <i>DOCKER_USERNAME</i>, <i>DOCKER_PASSWORD</i>).


title: USE CASES
content:
Common use cases for <b>crane mutate</b> include:<br>  - Adding security scan results as image labels.<br>  - Changing the entrypoint or CMD of a base image for specific deployments.<br>  - Stripping sensitive environment variables post-build.<br>  - Re-tagging an image with new version identifiers without a full re-push.<br>  - Applying patches (e.g., adding a security fix layer) without rebuilding the entire application.


title: HISTORY
content:
The <b>crane</b> utility, including its <i>mutate</i> subcommand, is part of the <i>go-containerregistry (pkg/crane)</i> project, developed primarily by Google. It emerged as a lightweight, Go-based tool for interacting with OCI (Open Container Initiative) compatible container registries without the need for a full Docker daemon. Its development aimed to provide more granular control and scripting capabilities for registry operations, particularly valuable in cloud-native build pipelines and CI/CD workflows where fast, direct registry interaction is crucial. The 'mutate' subcommand was introduced to address the need for modifying image metadata and layers post-build, offering a powerful alternative to re-building an entire image for minor configuration changes.


title: SYNOPSIS
content:
`crane pull <<i>source_image_reference</i>> <<i>destination_path</i>> [<i>options</i>>]<br><br><i>Examples:</i><br>`crane pull gcr.io/google-containers/alpine:latest alpine.tar`<br>`crane pull --format=oci-archive myregistry/myimage:v1 myimage.oci`<br>`crane pull --platform=linux/arm64 registry.example.com/app:latest app-arm64/`


title: PARAMETERS
content:
<b>--format <<i>format_type</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format for the pulled image. Supported formats include `oci-archive` (a tar archive in OCI layout), `docker-archive` (a tar archive in Docker image format), and `oci` (an OCI layout directory). Default is `oci-archive`.<br><br><b>--platform <<i>platform_spec</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects a specific platform (e.g., `linux/amd64`, `windows/arm64`) from a multi-platform image manifest list to pull.<br><br><b>--insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows connecting to registries over HTTP or with self-signed certificates, bypassing TLS verification.<br><br><b>--user-agent <<i>agent_string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overrides the default User-Agent header sent in HTTP requests to the registry.<br><br><b>--all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When used with `--format=oci`, pulls all platforms described by a multi-platform manifest list into the destination directory.<br><br>


title: DESCRIPTION
content:
The `crane pull` command is a subcommand of the <b>crane</b> utility, designed for efficiently downloading container images from OCI-compliant registries. It provides a flexible way to fetch image layers, manifests, and configurations, saving them to a local path in various formats. Unlike traditional container runtimes like Docker or Podman which often pull images into a local image store, `crane pull` writes the image directly to a specified local file or directory, making it ideal for CI/CD pipelines, image analysis, or transferring images without a local daemon. It supports authentication via standard Docker configuration files (`~/.docker/config.json`) and environment variables, and can handle multi-platform images, allowing users to specify a desired architecture. Its lightweight nature and direct interaction with registries make it a powerful tool for advanced image management.


title: CAVEATS
content:
`crane pull` is not a default Linux command; it requires the installation of the `crane` utility from the `go-containerregistry` project. Unlike `docker pull`, `crane pull` does not store images in a local daemon's image store; it writes them directly to disk. This means subsequent `docker run` commands won't automatically find images pulled by `crane pull` unless explicitly loaded (e.g., `docker load -i image.tar`). Be mindful of disk space, as pulled images can be large. Authentication for private registries relies on standard Docker credential helpers or environment variables, which must be configured correctly.


title: AUTHENTICATION
content:
`crane` automatically attempts to use standard Docker credential helpers and configuration files (like `~/.docker/config.json`) for authenticating with private registries. Users can also configure credentials via environment variables such as `DOCKER_USERNAME`, `DOCKER_PASSWORD`, or `DOCKER_TOKEN` for specific registries.


title: OUTPUT FORMATS EXPLAINED
content:
<ul><li><I>oci-archive:</I> Creates a `.tar` archive of the image in OCI image layout specification format. This is the default.</li><li><I>docker-archive:</I> Creates a `.tar` archive of the image in the Docker image format, compatible with `docker load`.</li><li><I>oci:</I> Creates a directory structure representing the OCI image layout, rather than a single archive file. This is useful for direct inspection or modification of the image contents.</li></ul>


title: HISTORY
content:
The `crane` tool is part of the `go-containerregistry` open-source project, initiated by Google. It was developed to provide a lightweight, programmatic way to interact with OCI and Docker registries using Go. The `crane` CLI, including the `pull` subcommand, emerged as a robust tool for performing low-level registry operations that might be cumbersome or impossible with higher-level container runtimes. Its focus on direct registry interaction and support for various image formats has made it popular in CI/CD environments and for specific image manipulation tasks outside the scope of typical `docker` or `podman` workflows.


title: SYNOPSIS
content:
<b>crane push</b> [<i>options</i>] <i>SOURCE</i> <i>DESTINATION</i><br><br><b><i>SOURCE</i></b>: Path to a local OCI image layout directory or a tarball containing an OCI layout/Docker image. E.g., /path/to/my-image-oci-layout or my-image.tar<br><b><i>DESTINATION</i></b>: Full registry path to the image, including repository and tag. E.g., registry.example.com/my-repo/my-image:latest


title: PARAMETERS
content:
<b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows connections to registries over HTTP or skips certificate validation for HTTPS, useful for local or insecure registries.<br><br><b><b>--tag</b> <i>&lt;tag&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds an additional tag to the pushed image. This option can be specified multiple times to add multiple tags.<br><br><b><b>--allow-nondistributable-artifacts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows pushing layers that might be marked as non-distributable by their original source (e.g., Windows base layers).<br><br><b><b>--platform</b> <i>&lt;platform&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When pushing an OCI layout containing multiple platforms, this option filters which specific platform(s) to push (e.g., <i>linux/amd64</i>). Can be specified multiple times.<br><br><b><b>--config</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a path to a JSON file containing the image configuration to use, overriding the default configuration from the source image.<br><br><b><b>--compress-level</b> <i>&lt;int&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the compression level for pushed blobs (layers). A value of <i>-1</i> uses the default, <i>0</i> for no compression, and <i>1-9</i> for increasing compression (default is often 5).<br><br><b><b>--verbose</b>, <b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose logging, providing more detailed output about the push process.<br><br>


title: DESCRIPTION
content:
<i>crane</i> is an open-source, daemon-less tool developed by Google, written in Go, for managing container images and registries. It provides various subcommands to inspect, modify, and transfer container images directly, without requiring a local Docker daemon.<br><br>The <b>crane push</b> command is specifically designed to upload a container image manifest and its associated layers (blobs) from a local source (typically an OCI image layout directory or a tarball) to a remote container registry. It serves as a lightweight and efficient alternative to <b>docker push</b>, particularly useful in automated CI/CD pipelines where a full Docker daemon might be undesirable or unavailable.<br><br><b>crane push</b> supports pushing multi-architecture images (manifest lists) and optimizes transfers by only pushing layers that do not already exist in the target registry, ensuring efficiency and reducing bandwidth usage. It can handle images from various local formats, including OCI layouts and Docker image tarballs.


title: CAVEATS
content:
<b>Authentication</b>: <i>crane</i> typically relies on standard Docker credential helpers (e.g., ~/.docker/config.json) or environment variables (e.g., DOCKER_USERNAME, DOCKER_PASSWORD) for registry authentication. Ensure credentials are configured before pushing.<br><br><b>Source Format</b>: <b>crane push</b> expects the source image to be in an OCI image layout directory or a compatible tarball. It does not directly push images from a local docker images list without first converting or saving them (e.g., using <i>crane save</i> or <i>docker save</i>).<br><br><b>Network Access</b>: Requires direct network connectivity to the target container registry and necessary firewall permissions.


title: AUTHENTICATION METHODS
content:
<i>crane</i> supports several authentication mechanisms for interacting with private registries: It first checks for credentials in the standard Docker configuration file (<i>~/.docker/config.json</i>). Alternatively, it can leverage environment variables like <i>DOCKER_USERNAME</i> and <i>DOCKER_PASSWORD</i>, or prompt interactively if no credentials are found and the registry requires authentication. For cloud provider registries (e.g., AWS ECR, GCP GCR), it often integrates with their respective credential helpers.


title: OCI IMAGE LAYOUTS
content:
The primary source format for <b>crane push</b> is the OCI (Open Container Initiative) image layout. This is a standardized on-disk format for container images, providing a structured directory that contains the image manifest, configuration, and layers (blobs). This layout can be generated by tools like <i>crane save</i>, <i>skopeo</i>, or even <i>docker save</i> (which outputs a similar tarball format that <i>crane</i> can often interpret).


title: HISTORY
content:
<i>crane</i> originated from the <i>go-containerregistry</i> library developed by Google. Its inception was driven by the increasing need for a lightweight, programmatic, and daemon-less method for interacting with container registries. This became particularly crucial in cloud-native environments and CI/CD pipelines where the overhead and dependencies of a full Docker daemon were undesirable. The <b>crane push</b> command, as a core functionality, reflects this design philosophy, offering a direct and efficient way to upload container images, distinguishing itself as a robust tool within the Kubernetes and container ecosystem.


title: SEE ALSO
content:
<b>docker push(1)</b>, <b>crane pull(1)</b>, <b>crane copy(1)</b>, <b>oras push(1)</b>, <b>skopeo copy(1)</b>


title: PARAMETERS
content:
<b><I>SOURCE_IMAGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full reference of the existing container image to be rebased (e.g., <I>myregistry/myimage:mytag</I>).<br><br><b><I>NEW_BASE_IMAGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full reference of the new base image that the source image will be rebased onto (e.g., <I>gcr.io/distroless/static:latest</I>).<br><br><b><I>TARGET_IMAGE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full reference where the rebased image will be pushed (e.g., <I>myregistry/myimage:newtag</I>).<br><br><b>-u, --username <I>USERNAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Username for authenticating with container registries.<br><br><b>-p, --password <I>PASSWORD</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Password for authenticating with container registries.<br><br><b>--insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow insecure HTTP connections or skip certificate verification for registry communication.<br><br><b>--platform <I>PLATFORM</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target platform for the image in the format <I>os/arch[/variant]</I> (e.g., <I>linux/amd64</I>). Can be specified multiple times for multi-platform images.<br><br><b>--allow-unverified-base</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Permit the new base image to be referenced by tag without requiring a digest, potentially leading to non-reproducible rebases if the base tag changes.<br><br><b>--allow-nondistributable-artifacts</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow pushing/pulling images that contain layers marked as non-distributable. Use with caution as these layers might not be transferable between all registries.<br><br>


title: DESCRIPTION
content:
<p>The <b>crane rebase</b> command is a powerful utility from the <b>go-containerregistry</b> project, designed to efficiently update the base layer of an existing container image without requiring a full rebuild of the application layers. Traditional methods of updating a base image often involve rebuilding the entire Dockerfile, which can be time-consuming and generate new, potentially larger, image layers.</p><br><p><b>crane rebase</b> works by inspecting the layers of the source image and comparing them with the layers of a specified new base image. It intelligently identifies the common layers and replaces the old base layers with the new ones, effectively "rebasing" the image. The unique application layers of the original image are then appended on top of the new base. This process primarily manipulates image manifests and layer pointers, making it significantly faster and more network-efficient than a full image build and push, especially when dealing with frequent security updates to common base images like Alpine or Debian.</p><br><p>This tool is particularly valuable in CI/CD pipelines for maintaining up-to-date and secure container images with minimal overhead.</p>


title: CAVEATS
content:
<ul><li><b>Layer Compatibility:</b> <b>crane rebase</b> expects a certain level of commonality between the old and new base images. If the new base image fundamentally changes its lower layers, the rebase operation might fail or produce unexpected results.</li><br><li><b>No Application Changes:</b> This command only modifies the base layers and manifest pointers. It does not re-execute any <I>Dockerfile</I> instructions above the base or rebuild application layers. Any changes required in the application's configuration or dependencies due to the new base must be handled by a full image rebuild.</li><br><li><b>Registry Access:</b> Proper authentication and network connectivity to both the source and target registries (and the new base image's registry) are crucial for successful operation.</li><br><li><b>Digest Pinning:</b> For reproducible builds, it's recommended to use digest-pinned image references for the <I>NEW_BASE_IMAGE</I> instead of tags, unless <I>--allow-unverified-base</I> is explicitly used.</li></ul>


title: HOW REBASE INTERNALLY WORKS
content:
<p>When <b>crane rebase</b> is executed, it performs the following conceptual steps:</p><br><ul><li><I>Fetch Manifests:</I> It pulls the manifests for the <I>SOURCE_IMAGE</I> and the <I>NEW_BASE_IMAGE</I> from their respective registries.</li><br><li><I>Layer Comparison:</I> It compares the ordered list of layer digests (diff IDs) from the <I>SOURCE_IMAGE</I> with those of the <I>NEW_BASE_IMAGE</I>. The command identifies the longest common sequence of layers between the original base of the <I>SOURCE_IMAGE</I> and the <I>NEW_BASE_IMAGE</I>.</li><br><li><I>Manifest Modification:</I> It constructs a new image manifest. The new manifest starts with the layers of the <I>NEW_BASE_IMAGE</I>, followed by the unique layers from the <I>SOURCE_IMAGE</I> that were built on top of its old base. This effectively swaps out the base layers.</li><br><li><I>Push New Image:</I> The modified manifest is then pushed to the <I>TARGET_IMAGE</I> location. Importantly, only the manifest itself and any new layers are pushed; existing layers (if common across images) are typically not re-uploaded, making the operation very efficient.</li></ul>


title: TYPICAL USE CASES
content:
<p><b>crane rebase</b> is invaluable in several scenarios:</p><br><ul><li><I>Security Patching:</I> Regularly updating application images to the latest patched versions of their base images (e.g., <I>debian:stable-slim</I> to <I>debian:stable-slim-YYYYMMDD</I>) to incorporate security fixes without rebuilding the application itself.</li><br><li><I>Base Image Upgrades:</I> Moving to a newer, compatible version of a base image (e.g., <I>distroless/static</I> to a newer digest) when no application-specific changes are required for the upgrade.</li><br><li><I>Reduced CI/CD Times:</I> Dramatically cuts down the time required for image updates in automated pipelines, as it avoids the lengthy <I>docker build</I> and subsequent <I>docker push</I> for every base image change.</li><br><li><I>Minimizing Storage and Network Traffic:</I> By avoiding full rebuilds and re-uploads of unchanged layers, it conserves registry storage and reduces network bandwidth consumption.</li></ul>


title: HISTORY
content:
<p>The <b>crane</b> tool is part of the <b>go-containerregistry</b> project, an open-source library and suite of command-line tools developed primarily by Google to interact with OCI (Open Container Initiative) image registries and images. The project's goal is to provide a robust, performant, and idiomatic Go API for managing container images, along with powerful CLI utilities like <b>crane</b>.</p><br><p><b>crane rebase</b> emerged as a specific solution to a common operational challenge: efficiently updating container images to incorporate security patches or newer versions of their base images without incurring the significant time and resource costs of a full image rebuild. It addresses the need for faster, more agile image maintenance in modern CI/CD pipelines, where minimizing build times and network traffic is paramount. Its development reflects the increasing maturity and sophistication of container image management practices.</p>


title: SYNOPSIS
content:
<b>crane</b> [<I>global-options</I>] <I>command</I> [<I>command-options</I>] [<I>arguments...</I>]<br><br>Common <I>registry-related commands</I> include:<br>&nbsp;&nbsp;<b>crane copy</b> <I>source-image</I> <I>destination-image</I><br>&nbsp;&nbsp;<b>crane ls</b> <I>registry/repository</I><br>&nbsp;&nbsp;<b>crane pull</b> <I>image-ref</I> <I>local-path</I><br>&nbsp;&nbsp;<b>crane push</b> <I>local-path</I> <I>image-ref</I><br>&nbsp;&nbsp;<b>crane auth login</b> <I>registry-url</I><br>&nbsp;&nbsp;<b>crane manifest</b> <I>image-ref</I>


title: PARAMETERS
content:
<b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output debug logs to diagnose issues.<br><br><b>--insecure</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow <i>insecure</i> registry connections via HTTP or skip TLS verification for HTTPS.<br><br><b>--platform</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a target platform (e.g., <I>linux/amd64</I>) for image operations like pulling or copying.<br><br><b>--allow-nondistributable-artifacts</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <b>copy</b> command, allows copying layers marked as non-distributable (e.g., Windows base layers).<br><br><b>--format</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the output format for commands like <b>ls</b> or <b>manifest</b> (e.g., <I>json</I>, <I>yaml</I>).<br><br><b>--tag</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <b>push</b> command, specifies a tag for the image being pushed.<br><br><b>--output</b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <b>pull</b> command, specifies the local path where the image content should be saved.<br><br>


title: DESCRIPTION
content:
<b>Crane</b> is a powerful, open-source command-line tool developed by GoogleContainerTools for <i>interacting directly</i> with OCI (Open Container Initiative) container images and registries.<br>It enables users to perform a wide array of operations without the need for a local Docker or Podman daemon, making it highly efficient for automated workflows and environments where a full container engine is unnecessary.<br>Key functionalities include <i>copying</i> images between registries, <i>inspecting</i> image manifests and layers, <i>listing</i> repository tags, and performing low-level <i>authentication</i> and image manipulation tasks.<br>Its design focuses on adherence to the OCI specification, ensuring compatibility and reliability for modern container ecosystems.


title: CAVEATS
content:
<b>crane</b> is not typically pre-installed with standard Linux distributions and usually requires manual installation (e.g., via Go toolchain or pre-built binaries).<br>It relies on network access to container registries, and proxy configurations might need specific environment variables to be set.<br>While highly compatible with OCI specifications, subtle differences in older or non-standard registry implementations might occasionally arise.<br>Error messages can sometimes be low-level, reflecting the direct interaction with registry APIs, which might require familiarity with OCI concepts.


title: DAEMONLESS OPERATION
content:
A key advantage of <I>crane</I> is its ability to operate independently of a local Docker or Podman daemon.<br>This makes it ideal for scripting, CI/CD pipelines, and environments where installing a full container runtime is impractical or undesirable, significantly reducing overhead and dependencies.


title: OCI COMPLIANCE
content:
<b>crane</b> is built to strictly adhere to the OCI Image Format Specification and Distribution Specification.<br>This ensures high compatibility with a wide range of modern container registries and allows for robust, predictable interactions with container images, promoting ecosystem interoperability.


title: TYPICAL USE CASES
content:
Beyond basic image copying, <I>crane</I> is extensively used for tasks like:<br>&nbsp;&nbsp;<i>Image Repackaging:</i> Modifying image manifests, adding signatures, or changing platforms.<br>&nbsp;&nbsp;<i>Vulnerability Scanning:</i> Extracting image layers for analysis without pulling the full image.<br>&nbsp;&nbsp;<i>Registry Mirroring:</i> Efficiently replicating images between different registry instances.<br>&nbsp;&nbsp;<i>Supply Chain Security:</i> Verifying image provenance and integrity, and pushing signed artifacts.


title: HISTORY
content:
<b>crane</b> originated from the <I>go-containerregistry</I> project by GoogleContainerTools.<br>It was developed to address the need for a lightweight, programmatic, and daemonless way to interact with container registries and OCI images.<br>Its development has focused on providing precise control over image layers and manifests, which is crucial for modern container supply chain security, image manipulation, and CI/CD automation. It has evolved as a core component in many automated container workflows.


title: SEE ALSO
content:
docker(1): General container management and image building., podman(1): Daemonless container management, alternative to Docker., skopeo(1): Similar tool for copying, inspecting, and deleting container images., oras(1): OCI Registry As Storage for arbitrary artifacts.


title: PARAMETERS
content:
<b>&lt;<i>SOURCE_IMAGE</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The reference to the source image to be tagged. This can be in the format of `<i>registry/repository:oldtag</i>` or `<i>registry/repository@sha256:...</i>`.<br><br><b>&lt;<i>TARGET_TAG</i>&gt;</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The new tag reference to be applied. This is typically in the format of `<i>registry/repository:newtag</i>`.<br><br><b><b>--allow-nondistributable-artifacts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow copying of nondistributable artifacts. Use with caution as these layers may not be supported by all registries.<br><br><b><b>--daemon-host</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the host of the daemon, if connecting to a daemon socket (e.g., for pulling from or pushing to a local Docker daemon). Default is `<i>unix:///var/run/docker.sock</i>`.<br><br><b><b>--platform</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target platform for the image (e.g., `<i>linux/amd64</i>`, `<i>linux/arm64</i>`, or `<i>all</i>` to tag all platforms in a multi-platform image). Only relevant if the source is a multi-platform image and you want to tag a specific platform.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display help information for the `tag` command.<br><br><b><b>--insecure</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allow connections to registries over HTTP or skip TLS verification. <i>Use with extreme caution in production environments.</i><br><br><b><b>--preserve-digests</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not remove the digest from the target tag. Defaults to `<i>true</i>`.<br><br><b><b>--repository</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the target repository for the new tag, if different from the source image's repository. Rarely used with `crane tag` as the target tag typically implies the repository.<br><br><b><b>--skip-tls-verify</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Skip TLS verification. Functionally similar to `<b>--insecure</b>` regarding TLS. <i>Use with extreme caution.</i><br><br><b><b>--user-agent</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom User-Agent string to use in registry requests.<br><br>


title: DESCRIPTION
content:
The `crane tag` command is a subcommand of the <b>crane</b> utility, designed for direct interaction with container registries. It allows users to apply a new tag to an existing image manifest within a remote registry without needing to pull the image locally. This command works by creating a new reference (tag) that points to the same underlying image manifest (identified by a digest or an existing tag).<br><br>This functionality is crucial for various container workflows, especially in CI/CD pipelines, where images need to be promoted through different environments (e.g., from `<i>dev</i>` to `<i>staging</i>` to `<i>production</i>`) or aliased for easier reference. Unlike `docker tag` which often involves local image manipulation and a subsequent push, `crane tag` operates entirely remotely, making it efficient for registry-to-registry operations or for updating tags on a remote image directly. It supports various registry authentication methods, typically leveraging `<i>~/.docker/config.json</i>` or environment variables.


title: CAVEATS
content:
<b>crane tag</b> requires network connectivity to the remote registry. <br>Appropriate authentication credentials and permissions for the target registry are mandatory for a successful operation. <br>Using `<b>--insecure</b>` or `<b>--skip-tls-verify</b>` flag should be avoided in production environments as it compromises security. <br>This command only manipulates tags and image manifests; it <i>does not</i> copy or alter the underlying image layers. It simply creates a new pointer to an existing image content.


title: REGISTRY AUTHENTICATION
content:
<b>crane</b> primarily uses the Docker configuration file (`<i>~/.docker/config.json</i>`) for authenticating with registries. It can also pick up credentials from environment variables such as `<i>DOCKER_USERNAME</i>` and `<i>DOCKER_PASSWORD</i>`.


title: IMMUTABILITY OF IMAGE CONTENT
content:
It is important to understand that <b>crane tag</b> does not change the actual image content. Instead, it creates a new tag that points to an existing image manifest (identified by its digest). This means if you tag `<i>myrepo/myimage@sha256:abcd</i>` with `<i>myrepo/myimage:newversion</i>`, both references point to the exact same immutable image layers. The image content remains unchanged.


title: COMMON USE CASES
content:
Common use cases include:<br><b>Promoting Images:</b> Tagging an image from a `<i>dev</i>` tag to a `<i>staging</i>` or `<i>production</i>` tag after successful testing.<br><b>Creating Release Tags:</b> Applying version-specific tags (e.g., `<i>v1.2.3</i>`) to an image that was previously tagged with `<i>latest</i>` or a build-specific identifier.<br><b>Aliasing:</b> Creating multiple convenient tags that all refer to the same immutable image.


title: HISTORY
content:
The `<b>crane</b>` utility is part of the `<i>go-containerregistry</i>` project, developed by Google, aimed at providing a set of Go libraries and CLIs for working with OCI (Open Container Initiative) image registries. `<b>crane tag</b>` is a fundamental subcommand that has been available since the early versions of `<b>crane</b>`. Its development was driven by the need for a lightweight, efficient tool to manage container images directly on remote registries without requiring a local Docker daemon or image pull/push operations. This makes it particularly valuable for automated build and release pipelines where direct registry manipulation is preferred for speed and simplicity.


title: PARAMETERS
content:
<b><I>image_reference</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The full OCI image or manifest list reference (e.g., <i>registry/repo:tag</i> or <i>registry/repo@sha256:digest</i>) to be validated.<br><br><b><b>-f</b>, <b>--full</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a full validation, including all referenced layers and blobs, in addition to the image manifest. By default, only the manifest is validated.<br><br><b><b>--platform</b> <I>string</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target platform (e.g., <i>linux/amd64</i>, <i>windows/arm64</i>) when validating a manifest list. This ensures validation for a specific architecture.<br><br><b><b>-r</b>, <b>--recursive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When validating a manifest list, this flag ensures that all individual images referenced within the list are also recursively validated.<br><br>


title: DESCRIPTION
content:
The <b>crane-validate</b> command is a subcommand of the <I>crane</I> utility, a powerful Go-based command-line tool developed by Google's <I>go-containerregistry</I> project. It is specifically designed to interact with remote Docker and OCI registries without requiring a local Docker daemon.<br><br>The primary function of <b>crane-validate</b> is to verify that a specified OCI (Open Container Initiative) image or manifest list adheres strictly to the OCI Distribution Specification. This ensures the integrity and correctness of container artifacts, making it an invaluable tool for CI/CD pipelines, conformance testing, and maintaining robust image supply chains.<br><br>By default, it primarily validates the image manifest. However, with the <i>--full</i> flag, it extends its validation to include all referenced layers and blobs, providing a comprehensive check. It also supports validating specific platforms within a multi-platform manifest list and recursively validating all images pointed to by a manifest list, ensuring broad applicability across various container image architectures.


title: CAVEATS
content:
<b>crane-validate</b> requires network connectivity to access the remote container registry where the image is stored. The validation performed is strictly against the OCI Distribution Specification, not necessarily for compatibility with specific container runtimes or Docker daemon versions.<br><br>The <I>crane</I> tool itself is an external utility and may need to be installed separately, as it is not typically part of standard Linux distribution packages.


title: USAGE EXAMPLES
content:
Here are some common usage patterns for <b>crane-validate</b>:<br><br><i>Validate a basic image manifest:</i><br><b>crane validate</b> <i>myregistry.com/myimage:latest</i><br><br><i>Perform a full validation, including all layers:</i><br><b>crane validate --full</b> <i>myregistry.com/myimage:v1.0</i><br><br><i>Validate a specific platform within a multi-arch manifest:</i><br><b>crane validate --platform</b> <i>linux/arm64 myregistry.com/multilayout:rc</i><br><br><i>Recursively validate all images referenced in a manifest list:</i><br><b>crane validate --recursive</b> <i>myregistry.com/app:latest</i>


title: EXIT STATUS
content:
The <b>crane-validate</b> command exits with a status of <b>0</b> if the image or manifest list passes all validation checks. A non-zero exit status indicates that validation failed due to non-compliance with the OCI specification or an operational error.


title: HISTORY
content:
The <I>crane</I> CLI tool emerged from Google's <I>go-containerregistry</I> project, which aimed to provide a robust Go library for interacting with OCI and Docker registries programmatically. The development of <I>crane</I>, and subsequently its <I>validate</I> subcommand, was driven by the need for a stateless, daemon-less tool to manage and inspect container images, crucial for serverless environments and CI/CD pipelines. The <b>validate</b> subcommand specifically addresses the critical requirement of ensuring image integrity and compliance with the evolving OCI specifications.


title: PARAMETERS
content:
<b>--json</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the version information in a machine-readable JSON format. This is particularly useful for programmatic parsing of <I>crane</I>'s version details in scripts.<br><br><b>-h, --help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display a help message for the <I>version</I> subcommand, providing information on its usage and available flags.<br><br>


title: DESCRIPTION
content:
<I>crane</I> is a powerful, open-source command-line tool developed by GoogleContainerTools for direct interaction with container registries (like Docker Hub, Google Container Registry, Azure Container Registry, etc.). Unlike <I>docker</I> or <I>podman</I>, <I>crane</I> operates daemon-less, making it ideal for scripting, CI/CD pipelines, and environments where a full container runtime isn't desired or available. It facilitates various operations such as copying images between registries, inspecting manifests, deleting tags, and more, all without requiring a local Docker daemon. The <I>crane version</I> command is a specific subcommand of the <I>crane</I> utility. Its sole purpose is to retrieve and display detailed build and release version information of the <I>crane</I> tool itself. This typically includes the application version number, Git commit hash, build timestamp, and the Go programming language version used to compile it. This information is crucial for debugging, ensuring compatibility, or simply verifying the installed tool's iteration.


title: CAVEATS
content:
The <I>crane version</I> command is a subcommand and relies on the <I>crane</I> executable being installed and accessible in the system's PATH. It only reports the version of the <I>crane</I> binary itself and does not involve any network interaction with container registries for its operation. The exact details provided (e.g., build date, Go version) depend on how the <I>crane</I> binary was compiled.


title: OUTPUT FORMAT
content:
By default, <I>crane version</I> outputs human-readable text, typically structured as 'Version: vX.Y.Z', 'GitCommit: <hash>', 'BuildDate: <timestamp>', and 'GoVersion: goX.Y.Z'. When the <I>--json</I> flag is used, the output transforms into a structured JSON object. This JSON output contains fields like <I>git_tag</I>, <I>git_commit</I>, <I>build_date</I>, and <I>go_version</I>, providing a machine-parsable format for automated systems.


title: HISTORY
content:
The <I>crane</I> tool emerged from GoogleContainerTools as an open-source project to address the need for lightweight, direct interaction with OCI-compliant container registries, bypassing the need for a full Docker daemon. Its development focused on providing robust functionalities for image manipulation and inspection. The <I>version</I> subcommand has been a fundamental part of <I>crane</I> since its early iterations, adhering to the common practice in command-line tools to provide easy access to their build metadata. This subcommand's consistent presence underscores its importance for users to quickly ascertain the tool's identity and build specifics, facilitating debugging and compatibility checks within continuous integration and deployment workflows.


title: PARAMETERS
content:
<b>[<I>FILE</I>]...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. One or more input files to calculate the CRC-32 checksum for. If no files are specified, <b>crc32</b> reads from standard input.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. Suppress the output of filenames, printing only the CRC-32 checksum.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. Display a help message and exit.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Optional</i>. Output version information and exit.<br><br>


title: DESCRIPTION
content:
The <b>crc32</b> command is a Linux utility designed to calculate the 32-bit <I>Cyclic Redundancy Check</I> (CRC-32) checksum of a given file or stream of data.<br><br>A CRC-32 checksum is a type of hash function used primarily for detecting accidental changes to raw data, such as those that might occur during data transmission or storage. It operates by performing a polynomial division on the input data, with the remainder being the checksum. The <b>crc32</b> utility reads data from the specified files; if no files are provided, it reads from standard input. The computed checksum is then printed to standard output, typically in an 8-character hexadecimal format.<br><br>While not cryptographically secure like <I>MD5</I> or <I>SHA</I> hashes (meaning it's easier to find two different inputs that produce the same CRC-32 checksum), <b>crc32</b> is efficient and widely used for non-cryptographic data integrity checks, such as verifying downloaded files or ensuring consistency of backups. It's particularly useful when speed is more critical than strong collision resistance.


title: CAVEATS
content:
The <b>crc32</b> command is designed for error detection, not cryptographic security. It is relatively easy to find collisions (different inputs producing the same checksum), making it unsuitable for verifying data integrity against malicious tampering. For cryptographic integrity, utilities like <b>md5sum</b> or <b>sha256sum</b> should be used instead.<br><br>Note that some rare or custom <b>crc32</b> implementations might use different polynomial or initial values, potentially yielding different checksums for the same data, though the standard CRC-32 (IEEE 802.3) is almost universally adopted in common Linux utilities.


title: USAGE AND OUTPUT
content:
By default, <b>crc32</b> prints the computed checksum as an 8-character hexadecimal string, followed by a space and the filename for each processed file. If reading from standard input, only the checksum is printed.<br><br><i>Examples:</i><br>To calculate the CRC-32 of a file:<br><b>crc32</b> <I>mydata.txt</I><br><i>Output:</i> <I>1a2b3c4d mydata.txt</I><br><br>To calculate the CRC-32 of a string from standard input:<br><b>echo</b> "<i>Hello World</i>" | <b>crc32</b><br><i>Output:</i> <I>cbefcb75</I><br><br>To calculate the CRC-32 of multiple files silently:<br><b>crc32</b> -s <I>file1.txt file2.txt</I><br><i>Output:</i><br><I>abcdef12</I><br><I>34567890</I>


title: HISTORY
content:
The concept of Cyclic Redundancy Checks (CRCs) dates back to the early 1960s, with CRC-32 becoming standardized, notably by the <I>IEEE 802.3 Ethernet</I> standard and popularized by applications like <I>PKZIP</I>. The <b>crc32</b> command-line utility itself emerged as a simple wrapper around the widely available CRC-32 algorithms, often leveraging libraries like <I>zlib</I> which provide highly optimized CRC computation functions. Its development reflects the pervasive need for quick and efficient data integrity verification in various computing contexts, from network transmissions to file storage and archiving, becoming a standard tool in Linux environments for non-cryptographic checksumming.


title: PARAMETERS
content:
<b><I>COUNTRY_CODE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The two-letter ISO 3166-1 alpha-2 country code (e.g., 'US', 'DE', 'JP') for which to apply wireless regulatory rules. This is the primary argument <i>crda</i> expects when explicitly invoked, though it's typically triggered by system services.<br><br>


title: DESCRIPTION
content:
<i>crda</i> is the <b>Central Regulatory Domain Agent</b> in Linux, responsible for enforcing wireless regulatory rules based on geographic location. It ensures that wireless devices like Wi-Fi adapters operate within the legal limits of a specific country, controlling aspects such as available frequencies, maximum transmit power, and allowed channels.<br><br>It achieves this by reading a digitally signed regulatory database (typically <i>/lib/firmware/regulatory.db</i>) which contains country-specific regulatory information. When the system detects a wireless device or the country code changes, <i>crda</i> is invoked (often via <i>udev</i> or network managers) to inform the kernel's <i>cfg80211</i> subsystem about the applicable regulatory domain. This prevents wireless devices from operating illegally or causing interference, ensuring compliance with local regulations worldwide.


title: CAVEATS
content:
Requires a valid and digitally signed regulatory database (<i>regulatory.db</i>). If the database is missing, corrupted, or the signature is invalid, <i>crda</i> might fail to set regulatory rules, potentially leading to limited Wi-Fi functionality or no Wi-Fi at all.<br><br>It relies heavily on the kernel's <i>cfg80211</i> subsystem for interaction. An incorrect country code can lead to non-compliance with local laws or suboptimal wireless performance due to unnecessary restrictions. For ongoing compliance, the regulatory database must be kept up-to-date.<br><br><i>crda</i> typically requires elevated privileges to operate, usually running as root or via privileged mechanisms orchestrated by the system.


title: REGULATORY DATABASE
content:
The regulatory database, typically found at <i>/lib/firmware/regulatory.db</i>, is crucial for <i>crda</i>'s operation. This database is cryptographically signed, and <i>crda</i> verifies this signature before applying its rules, ensuring data authenticity and integrity. It contains comprehensive information on allowed frequencies, power levels, and channel availability for various countries worldwide.


title: INTERACTION WITH IW
content:
While <i>crda</i> is the underlying agent, users typically do not invoke it directly. Instead, they commonly use the <i>iw</i> command (e.g., <i>iw reg set US</i>), which sends a Netlink message to the kernel. The kernel then triggers <i>crda</i> to process and apply the specified country's regulations based on this input.


title: AUTOMATIC INVOCATION
content:
<i>crda</i> is frequently invoked automatically by <i>udev</i> rules when a wireless device is detected or initialized, or by network managers upon system boot or network configuration changes. This automated process ensures that the correct regulatory domain is applied seamlessly without manual user intervention, crucial for system stability and compliance.


title: HISTORY
content:
<i>crda</i> was developed as an integral part of the modern Linux wireless stack, specifically alongside the <i>cfg80211</i> kernel subsystem and <i>mac80211</i> drivers. Its introduction addressed the need for a robust and centralized mechanism to manage wireless regulatory compliance. Prior to <i>crda</i>, regulatory information was often hardcoded in individual wireless drivers, leading to inflexibility and potential compliance issues.<br><br>The design of <i>crda</i>, coupled with a digitally signed <i>regulatory.db</i>, ensures the integrity and authenticity of the regulatory data, preventing unauthorized modifications. It has since become a standard and essential component in most contemporary Linux distributions for managing Wi-Fi regulatory domains.


title: SYNOPSIS
content:
<b>create-cracklib-dict</b> [<i>FILE...</i>]<br><b>create-cracklib-dict</b> <i>&lt;</i> <i>WORDLIST_FILE</i>


title: DESCRIPTION
content:
The <b>create-cracklib-dict</b> command is a utility used to build or refresh the dictionary files for the <i>CrackLib</i> password strength checking library. It processes one or more word list files (or standard input) and converts them into a highly optimized, indexed database format that <i>CrackLib</i> can quickly search. This dictionary is crucial for <i>CrackLib</i>'s function, enabling it to efficiently identify weak passwords that are simple dictionary words or common patterns. The generated dictionary typically resides in <i>/var/lib/cracklib/cracklib_dict.{hwm,pwc,rec}</i> and is subsequently used by tools like <b>cracklib-check</b> to enforce strong password policies on Linux and Unix-like systems. Building a comprehensive dictionary is a fundamental step in deploying effective password security.


title: CAVEATS
content:
<b>Root Privileges</b>: Requires administrative (root) privileges to write to the default system dictionary location (typically <i>/var/lib/cracklib</i>).<br><b>Time Consumption</b>: Processing very large wordlists can be time-consuming and resource-intensive.<br><b>Dictionary Size Impact</b>: While a larger dictionary improves password cracking resistance, an excessively large dictionary can slightly impact the performance of password validation checks.<br><b>Input Format</b>: Wordlist files must contain one word per line.


title: DEFAULT DICTIONARY PATH
content:
The dictionary files generated by <b>create-cracklib-dict</b> are typically stored in <i>/var/lib/cracklib/cracklib_dict.{hwm,pwc,rec}</i>. These three files collectively form the compressed and indexed <i>CrackLib</i> dictionary database.


title: TYPICAL USAGE
content:
A common way to create the dictionary is by piping a standard wordlist to the command, for example:<br><i>cat /usr/share/dict/words | create-cracklib-dict</i><br>or by specifying multiple files:<br><i>create-cracklib-dict /usr/share/dict/words /opt/my_custom_words.txt</i>


title: UNDERLYING MECHANISM
content:
The <b>create-cracklib-dict</b> command is often a shell script wrapper that calls the lower-level utility <b>cracklib-packer</b>. It simplifies the process of creating the dictionary by handling paths and input/output redirection.


title: HISTORY
content:
The <i>CrackLib</i> suite, including <b>create-cracklib-dict</b>, was primarily developed by <i>Alec Muffett</i>. It emerged as a response to the pervasive issue of weak passwords in computing systems. Its development focused on providing a robust and efficient mechanism for system administrators to enforce stronger password policies. <i>CrackLib</i> quickly became a de-facto standard in Unix and Linux environments, integrated into PAM (Pluggable Authentication Modules) and other authentication mechanisms to prevent users from choosing easily guessable passwords. The command's core function, packing dictionaries, has remained central to its operation since its inception.


title: SYNOPSIS
content:
<b><I>create-image</I></b> <I>[OPTIONS]</I> <I>&lt;output-path&gt;</I><br><b><I>create-image</I></b> <I>[OPTIONS]</I> <I>&lt;image-type&gt;</I> <I>&lt;output-path&gt;</I><br><I>A conceptual command. Real-world image creation involves specific tools.</I>


title: PARAMETERS
content:
<b>--size <SIZE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the size of the image, e.g., "10G", "500M".<br><br><b>--format <FORMAT></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the image format, such as "raw", "qcow2", "vmdk", "iso".<br><br><b>--type <TYPE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Categorizes the image, e.g., "vm", "container", "bootable".<br><br><b>--template <TEMPLATE_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a predefined OS or application template for the image content.<br><br><b>--os <OS_NAME></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the operating system when using a template, e.g., "centos-stream-8", "ubuntu-22.04".<br><br><b>--filesystem <FS_TYPE></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Formats the image with a specific filesystem, e.g., "ext4", "xfs", "fat32".<br><br><b>--source <PATH></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a directory or existing image to use as source content.<br><br><b>--bootable</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Configures the image to be bootable.<br><br><b>--sparse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a sparse image file, which only consumes space as data is written.<br><br><b>--compress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Compresses the image file to reduce its size.<br><br>


title: DESCRIPTION
content:
The term "<I>create-image</I>" on Linux typically refers to the conceptual process of generating disk images or virtual machine images, rather than a single, universally recognized command. This process involves creating a file that represents a storage device, often including a filesystem and operating system, for purposes like virtualization, containerization, or creating bootable media. While no single command named "<I>create-image</I>" exists, various specialized tools are used to achieve this, such as <I>dd</I> for raw disk cloning, <I>qemu-img</I> for virtual machine disk formats, <I>mkfs</I> for filesystem creation, and image builders like <I>virt-builder</I> for complete OS images. The complexity varies from simple empty image files to fully provisioned virtual machines.


title: CAVEATS
content:
The command "<I>create-image</I>" is not a standard, standalone utility found in most Linux distributions. The functionality described typically involves a suite of specialized tools. Users must identify the specific tool suitable for their image creation needs (e.g., <I>qemu-img</I> for VM disks, <I>dd</I> for raw copies, <I>virt-builder</I> for complex VM images, <I>mkisofs</I>/<I>genisoimage</I> for ISOs). Incorrect usage of these tools can lead to data loss or system instability.


title: VIRTUAL MACHINE DISK IMAGES
content:
These images (<I>.qcow2</I>, <I>.vmdk</I>, <I>.vdi</I>, <I>.raw</I>) are used by hypervisors to store the virtual disk of a VM. They can be created empty and formatted later, or built from a template with an OS pre-installed.


title: CONTAINER IMAGES
content:
While not traditional "disk images," container images (<I>Docker</I>, <I>OCI</I> format) bundle applications and their dependencies. They are built layer by layer using tools like <I>Buildah</I> or <I>Docker build</I> and are designed for portability and isolation.


title: BOOTABLE MEDIA IMAGES
content:
These include ISO images for optical media or raw images for USB drives. They contain a bootloader and an operating system, allowing systems to boot directly from them for installation or live environments.


title: HISTORY
content:
The concept of creating system or disk images on Linux has evolved significantly with the rise of virtualization (like KVM, VirtualBox), containerization (Docker, Podman, LXC), and cloud computing. Initially, simple raw disk images could be created with tools like <I>dd</I>. As needs grew, more sophisticated tools emerged to handle complex virtual disk formats (<I>qcow2</I>, <I>vmdk</I>), automate OS provisioning (<I>virt-builder</I>, <I>packer</I>), and manage container images (<I>buildah</I>, <I>docker build</I>). There has never been a single, unified "<I>create-image</I>" command; instead, the ecosystem developed domain-specific tools, each optimized for a particular type of image creation.


title: SEE ALSO
content:
dd(1), qemu-img(1), virt-builder(1), mkfs(8), mount(8), losetup(8), fdisk(8), parted(8), genisoimage(1), tar(1), rsync(1)


title: SYNOPSIS
content:
<b>createdb</b> [<i>connection-options</i>] [<i>option...</i>] [<i>dbname</i> [<i>template</i>]]<br><br><i>connection-options</i>: <br>&nbsp;&nbsp;<b>-h</b> <i>host</i>, <b>--host=</b><i>host</i><br>&nbsp;&nbsp;<b>-p</b> <i>port</i>, <b>--port=</b><i>port</i><br>&nbsp;&nbsp;<b>-U</b> <i>username</i>, <b>--username=</b><i>username</i><br>&nbsp;&nbsp;<b>-W</b>, <b>--password</b><br><br><i>option...</i>: <br>&nbsp;&nbsp;<b>-D</b> <i>tablespace</i>, <b>--tablespace=</b><i>tablespace</i><br>&nbsp;&nbsp;<b>-E</b> <i>encoding</i>, <b>--encoding=</b><i>encoding</i><br>&nbsp;&nbsp;<b>-e</b>, <b>--echo</b><br>&nbsp;&nbsp;<b>-l</b> <i>locale</i>, <b>--locale=</b><i>locale</i><br>&nbsp;&nbsp;<b>-O</b> <i>owner</i>, <b>--owner=</b><i>owner</i><br>&nbsp;&nbsp;<b>-T</b> <i>template</i>, <b>--template=</b><i>template</i><br>&nbsp;&nbsp;<b>-V</b>, <b>--version</b><br>&nbsp;&nbsp;<b>-?</b>, <b>--help</b><br><br><i>dbname</i>: The name of the new database to create.<br><i>template</i>: The name of the template database to copy (default is <i>template1</i>).


title: PARAMETERS
content:
<b><b>-D</b> <i>tablespace</i>, <b>--tablespace=</b><i>tablespace</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the default tablespace for the new database.<br><br><b><b>-E</b> <i>encoding</i>, <b>--encoding=</b><i>encoding</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character set encoding to use for the new database.<br><br><b><b>-e</b>, <b>--echo</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Echoes the commands that <i>createdb</i> generates and sends to the server. Useful for debugging.<br><br><b><b>-l</b> <i>locale</i>, <b>--locale=</b><i>locale</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the locale settings (<i>LC_CTYPE</i> and <i>LC_COLLATE</i>) to be used in the new database.<br><br><b><b>-O</b> <i>owner</i>, <b>--owner=</b><i>owner</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the role name of the user who will own the new database.<br><br><b><b>-T</b> <i>template</i>, <b>--template=</b><i>template</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the template database to copy. Defaults to <i>template1</i>.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <i>createdb</i> version and exits.<br><br><b><b>-?</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows help about <i>createdb</i> command line arguments and exits.<br><br><b><b>-h</b> <i>host</i>, <b>--host=</b><i>host</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the host name of the machine on which the PostgreSQL server is running. If empty, the local Unix domain socket is used.<br><br><b><b>-p</b> <i>port</i>, <b>--port=</b><i>port</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections.<br><br><b><b>-U</b> <i>username</i>, <b>--username=</b><i>username</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;User name to connect as (defaults to current operating system user).<br><br><b><b>-W</b>, <b>--password</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <i>createdb</i> to prompt for a password before connecting to the database.<br><br>


title: DESCRIPTION
content:
<i>createdb</i> is a utility for creating new PostgreSQL databases. It is a wrapper around the SQL command <b>CREATE DATABASE</b>, which is executed on a PostgreSQL server. This command simplifies the process of database creation by abstracting away the need to manually connect to <i>psql</i> and execute the <b>CREATE DATABASE</b> statement. It requires a running PostgreSQL server and appropriate permissions for the connecting user to create databases.<br><br>Essentially, <i>createdb</i> connects to a specified PostgreSQL instance (or the default one) and sends the instruction to create a database with the given name and options. If a template database is specified, the new database will be a copy of that template; otherwise, it will copy from the default <i>template1</i>.


title: CAVEATS
content:
The PostgreSQL server must be running and accessible for <i>createdb</i> to connect successfully.<br>The user running <i>createdb</i> must have the <b>CREATEDB</b> privilege in PostgreSQL to create new databases.<br>Encoding and locale settings are permanent for a database and cannot be changed after creation without dropping and recreating the database.<br>When creating a database from a template, any objects or data present in the template will be copied to the new database. Be mindful if <i>template1</i> (the default) has been modified.


title: SECURITY CONSIDERATIONS
content:
Avoid hardcoding passwords directly in shell scripts. Instead, use environment variables like <b>PGPASSWORD</b>, or preferably, a <i>.pgpass</i> file for secure password storage. Ensure the PostgreSQL user specified with <b>-U</b> has only the necessary privileges (e.g., <b>CREATEDB</b>) and not excessive administrative rights.


title: COMMON USE CASES
content:
<i>createdb</i> is commonly used for automating database creation as part of application deployment pipelines, setting up development or test environments quickly, or creating databases with specific character sets and locale settings for internationalization requirements.


title: HISTORY
content:
<i>createdb</i> has been an integral part of the PostgreSQL client utilities since its early versions, providing a straightforward command-line interface to the <b>CREATE DATABASE</b> SQL command. Its design reflects the common need for scripting database setup and management tasks without directly interacting with <i>psql</i>. Its functionality has remained largely consistent, evolving primarily with new features in PostgreSQL databases themselves, such as support for tablespaces, different encoding options, and improved connection parameters.


title: PARAMETERS
content:
<b><b>--update</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Update an existing repository incrementally, processing only new or changed packages.</i><br><br><br><b><b>--database</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Generate a SQLite database alongside the XML metadata for faster client lookups.</i><br><br><br><b><b>-o</b> <i>&lt;path&gt;</i>, <b>--output</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify the output directory for the repository metadata. Defaults to &lt;directory&gt;/repodata/.</i><br><br><br><b><b>-x</b> <i>&lt;glob&gt;</i>, <b>--exclude</b> <i>&lt;glob&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Exclude packages matching the specified glob pattern from the repository.</i><br><br><br><b><b>--workers</b> <i>&lt;num&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Set the number of worker processes or threads to use for parallel processing.</i><br><br><br><b><b>--retain-old-md</b> <i>&lt;num&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specify how many previous sets of repository metadata to retain. Useful for clients with older metadata caches.</i><br><br><br><b><b>--pretty</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Pretty-print the generated XML metadata files for better human readability.</i><br><br><br><b><b>--c9s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Generate repository metadata using algorithms specific to CentOS Stream 9, typically for modular content.</i><br><br><br>


title: DESCRIPTION
content:
<i>createrepo</i> is a utility used to create and update a YUM or DNF repository. It scans a specified directory containing RPM packages and generates the necessary metadata files (XML files, often gzip compressed) that YUM/DNF clients use to locate, verify, and install packages. These metadata files, typically stored in a <I>repodata/</I> subdirectory, include information about package names, versions, dependencies, file lists, and more. <i>createrepo</i> is essential for setting up local or network-based RPM repositories, enabling efficient package management within an organization or for custom software distribution. It supports incremental updates via the <I>--update</I> option, allowing only new or changed packages to be processed, which significantly saves time and resources for large repositories.


title: CAVEATS
content:
Creating or updating very large repositories can be resource-intensive (CPU, memory, disk I/O).<br>The <I>--update</I> option relies on package timestamps and checksums; ensure consistent time synchronization across systems if packages are moved.<br>Requires write permissions to the target repository directory and its subdirectories.<br>The original <I>createrepo</I> (Python-based) is often replaced by or acts as a wrapper for <I>createrepo_c</I> (C-based) for performance improvements.


title: REPOSITORY STRUCTURE
content:
The metadata generated by <I>createrepo</I> is typically placed in a subdirectory named <I>repodata/</I> within the main repository directory. This directory contains key files such as <I>repomd.xml</I> (the main repository metadata index), <I>primary.xml.gz</I> (containing essential package information), <I>filelists.xml.gz</I> (listing all files within packages), and <I>other.xml.gz</I> (for miscellaneous package data).<br>


title: INCREMENTAL UPDATES
content:
Using the <I>--update</I> option is crucial for efficiency when maintaining large repositories, as it avoids regenerating all metadata from scratch. Instead, it only processes new or modified RPMs, comparing them against existing metadata and updating only what's necessary. This can drastically reduce the time and computational resources required for repository maintenance.<br>


title: HISTORY
content:
The <I>createrepo</I> utility emerged with the advent of YUM (Yellowdog Updater, Modified) as the primary package manager for Red Hat-based Linux distributions, succeeding <I>up2date</I>. Initially written in Python, its purpose was to provide the necessary metadata infrastructure for YUM to function effectively by processing RPM packages into a repository structure. Over time, especially with the growth of repository sizes and the demand for improved performance, a C-based implementation, <I>createrepo_c</I>, was developed. This C version is significantly faster and more memory-efficient, often replacing the original Python version or being called by it as a backend. Its development is closely tied to the evolution of YUM and subsequently DNF package managers, remaining a critical component for managing local and remote RPM repositories.


title: PARAMETERS
content:
<b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the game from a random point, allowing for varied starting hands instead of always from the beginning.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the running scores during the pegging phase of each hand, providing real-time score updates.<br><br><b><b>-p</b> <i>number</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the game's winning score to <i>number</i> points instead of the default 121 points.<br><br><b><b>-o</b> <i>score</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the user's score at <i>score</i> points, which can be useful for practicing specific game scenarios or starting a game mid-way.<br><br>


title: DESCRIPTION
content:
The <b>cribbage</b> command allows users to play the traditional card game of Cribbage against the computer. The computer acts as the dealer and always deals the first hand. Gameplay involves dealing cards, discarding two cards to the crib (both by the user and the computer), and then playing out the hand by pegging points. After the pegging phase, hands and cribs are counted. The game continues until one player reaches a score of 121 points. The program prompts the user for card selections during discarding and pegging, and the computer attempts to make optimal plays.


title: CAVEATS
content:
The computer opponent, while generally capable, might not always make the absolute optimal play in all situations. Some less common or nuanced Cribbage rules might not be fully implemented in older versions of the command.


title: GAMEPLAY INTERACTION
content:
Users interact with the <b>cribbage</b> command by typing in card selections when prompted. For instance, during the discard phase, the user will be asked to choose two cards for the crib. During the pegging phase, the user chooses a card to play based on the current count. The program handles all scoring and game state management, indicating whose turn it is and the current pegging total.<br><br>The game continues turn-by-turn with card plays and point counting, until one player reaches the target score (default 121).


title: HISTORY
content:
The <b>cribbage</b> command is a classic Unix game, often found in the <i>games</i> section of system distributions. Its origins trace back to early Unix systems, providing a simple interactive game for users on text-based terminals. It exemplifies the early tradition of including recreational programs within the Unix environment, demonstrating basic AI for card games. While its core functionality remains largely unchanged, its presence is a nod to the historical Unix gaming suite.


title: SYNOPSIS
content:
<b>crictl</b> [<i>GLOBAL_OPTIONS</i>] <i>COMMAND</i> [<i>COMMAND_OPTIONS</i>] [<i>ARGUMENTS</i>]<br><br><i>Examples:</i><br><b>crictl ps</b><br><b>crictl images</b><br><b>crictl pull</b> <i>nginx:latest</i><br><b>crictl logs</b> <i>&lt;container_id&gt;</i>


title: PARAMETERS
content:
<b><b>-D</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Enable debug output.</i><br><br><b><b>--runtime-endpoint</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Endpoint of CRI runtime service (e.g., "unix:///var/run/containerd/containerd.sock").</i><br><br><b><b>--image-endpoint</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Endpoint of CRI image service (often same as runtime endpoint).</i><br><br><b><b>--timeout</b> <i>&lt;duration&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Timeout for connecting to the server (e.g., "5s").</i><br><br><b><b>--config</b> <i>&lt;path&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Path to the <b>crictl</b> config file (e.g., "/etc/crictl.yaml").</i><br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show version information.</i><br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Show help message.</i><br><br>


title: DESCRIPTION
content:
<b>crictl</b> is a command-line interface tool that provides a common set of commands to interact with <I>CRI-compatible</I> container runtimes (like <b>containerd</b>, <b>CRI-O</b>) on a Kubernetes node. It's designed primarily for debugging and troubleshooting purposes, allowing administrators and developers to inspect and manage containers, pods, images, and other resources managed by the <I>Container Runtime Interface</I> (CRI). Unlike general-purpose container management tools such as <b>docker</b> or <b>podman</b>, <b>crictl</b>'s primary focus is on the specific interactions required by Kubernetes.<br><br>It allows users to list pods, containers, and images; pull images; create sandboxes; run containers; and more, mimicking some of the functionalities that <b>kubelet</b> uses internally to communicate with the container runtime. This makes <b>crictl</b> an invaluable tool for understanding and diagnosing issues within the Kubernetes container ecosystem, especially when direct interaction with the container runtime is needed.


title: CAVEATS
content:
<b>crictl</b> is primarily a debugging and troubleshooting tool for Kubernetes nodes, not a general-purpose container management tool. Its functionality is tied to the <I>Container Runtime Interface</I> (CRI) specification, meaning it interacts directly with CRI-compliant runtimes (like <b>containerd</b> or <b>CRI-O</b>). Behavior and available features can vary slightly depending on the specific underlying runtime and its version. It requires direct access to the Kubernetes node where the container runtime is running.


title: USE CASES
content:
<b>crictl</b> is invaluable for:<br><ul><li>Debugging <B>kubelet</B> issues or container startup failures.</li><li>Verifying the status of the container runtime and its managed resources.</li><li>Inspecting container images and their metadata.</li><li>Force-removing stuck or misbehaving pods/containers when <B>kubectl</B> commands are insufficient.</li><li>Understanding the direct interactions between <B>kubelet</B> and the underlying container runtime via the CRI API.</li></ul>


title: CONFIGURATION
content:
<b>crictl</b> can be configured using a YAML file, typically located at <i>/etc/crictl.yaml</i> or <i>~/.crictl.yaml</i>. This configuration file allows users to specify the default runtime endpoint, image endpoint, and timeout settings, avoiding the need to pass them as command-line arguments repeatedly.


title: HISTORY
content:
<b>crictl</b> was developed as part of the Kubernetes project to provide a consistent way to interact with various <I>Container Runtime Interface</I> (CRI) implementations. Its emergence parallels Kubernetes' evolution towards greater runtime independence. Before CRI, Kubernetes often had tight coupling with specific runtimes like Docker. The introduction of CRI abstracted runtime specifics, and <b>crictl</b> became the standard CLI tool for administrators and developers to debug and inspect the state of containers and pods directly on a Kubernetes node, bypassing <b>kubectl</b> and interacting with the underlying runtime services (e.g., containerd or CRI-O) via the CRI API. This provides a crucial layer for diagnosing issues between <b>kubelet</b> and the container runtime.


title: PARAMETERS
content:
<b><b><I>-inform</I></b> <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input format of the CRL. Common arguments are <i>PEM</i> (default) and <i>DER</i>.<br><br><b><b><I>-outform</I></b> <I>arg</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output format of the CRL. Common arguments are <i>PEM</i> (default) and <i>DER</i>.<br><br><b><b><I>-in</I></b> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input CRL file. If not specified, standard input is used.<br><br><b><b><I>-out</I></b> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output CRL file. If not specified, standard output is used.<br><br><b><b><I>-text</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the CRL in a human-readable text form, showing all its details.<br><br><b><b><I>-noout</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the output of the encoded (raw) version of the CRL.<br><br><b><b><I>-issuer</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the issuer name of the CRL.<br><br><b><b><I>-lastupdate</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <I>lastUpdate</I> field of the CRL, indicating when it was last issued.<br><br><b><b><I>-nextupdate</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the <I>nextUpdate</I> field of the CRL, indicating when the next CRL is expected.<br><br><b><b><I>-CA</I></b> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;File containing the CA certificate to use for signing or verifying the CRL.<br><br><b><b><I>-CAkey</I></b> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;File containing the CA private key to use for signing the CRL.<br><br><b><b><I>-crldays</I></b> <I>num</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of days for which a newly generated CRL will be valid.<br><br>


title: DESCRIPTION
content:
The <b><I>crl</I></b> command, typically invoked as <b><I>openssl crl</I></b>, is a versatile utility within the OpenSSL toolkit designed for managing Certificate Revocation Lists (CRLs). CRLs are vital components of a Public Key Infrastructure (PKI), serving as a blacklist of certificates that have been revoked by their issuing Certificate Authority (CA) before their scheduled expiration date. This prevents the continued use of compromised or otherwise invalidated certificates.<br><br>Users can employ <b><I>openssl crl</I></b> to perform various operations, including generating new CRLs, updating existing ones by adding new revocation entries, verifying the digital signature of a CRL to ensure its authenticity, and examining its contents in a human-readable format. It provides comprehensive options for handling input and output formats (PEM, DER), specifying cryptographic details for signing, and managing validity periods. This command is an indispensable tool for administrators responsible for maintaining the security and integrity of certificate-based systems.


title: CAVEATS
content:
The string 'crl.1s' is not a standard, executable Linux command on most systems. The command likely being referred to is 'crl' as a subcommand of the <b><I>openssl</I></b> utility, invoked as <b><I>openssl crl</I></b>. The '.1s' part in 'crl.1s' is atypical for a manual page section reference; standard sections are usually a single digit (e.g., '1' for user commands, '8' for administration commands). It might indicate a non-standard manual page or a misunderstanding of manual page syntax. Misuse of CRL management can lead to security vulnerabilities or service outages in PKI environments.


title: CRL FUNCTION IN PKI
content:
CRLs provide a mechanism for CAs to announce that specific certificates are no longer valid, even if their validity period has not yet expired. This is crucial for responding to security incidents like private key compromise or administrative changes such as an employee leaving an organization. When a client verifies a certificate, it typically checks the corresponding CRL to ensure the certificate has not been revoked.


title: CRL VS. OCSP
content:
CRLs are a push-based mechanism where a list of revoked certificates is periodically published. An alternative, more real-time mechanism is OCSP (Online Certificate Status Protocol), which allows for immediate, on-demand status checks of individual certificates. While OCSP offers lower latency for revocation checks, CRLs are simpler to implement and manage for smaller scale or less time-critical revocation needs.


title: HISTORY
content:
The <b><I>crl</I></b> subcommand is an integral part of the OpenSSL project, which began in 1998 as a collaborative effort building upon the SSLeay library, originally developed by Eric Young and Tim Hudson. OpenSSL quickly became the de facto standard for cryptographic operations and SSL/TLS implementations across various platforms. The <b><I>crl</I></b> command has evolved with the broader OpenSSL library, incorporating support for new cryptographic algorithms, extensions, and best practices in PKI management, maintaining its role as a fundamental tool for handling Certificate Revocation Lists.


title: SYNOPSIS
content:
<b>openssl crl2pkcs7</b> [<I>options</I>]<br>General syntax: <b>openssl crl2pkcs7</b> <b>-in</b> <I>crl_filename</I> <b>-out</b> <I>pkcs7_filename</I> [<I>additional_options</I>]


title: PARAMETERS
content:
<b>-in <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input file containing the CRL(s) to be converted. If omitted, standard input is used.<br><br><b>-out <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file for the resulting PKCS#7 structure. If omitted, standard output is used.<br><br><b>-inform <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the input format of the CRL(s), typically <B>PEM</B> (default) or <B>DER</B>.<br><br><b>-outform <I>format</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the output format of the PKCS#7 structure, typically <B>PEM</B> (default) or <B>DER</B>.<br><br><b>-nocrl</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the output of any CRLs in the PKCS#7 structure, useful when only embedding certificates via <B>-certfile</B>.<br><br><b>-noverify</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables verification of the input CRL's signature. Use with caution, as it can lead to processing untrusted CRLs.<br><br><b>-certfile <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an additional file containing certificates to be included in the PKCS#7 structure alongside the CRL(s).<br><br><b>-crlfile <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an additional file containing CRLs to be appended to the input CRL(s) in the PKCS#7 structure.<br><br>


title: DESCRIPTION
content:
The <b>openssl crl2pkcs7</b> command is a utility within the OpenSSL toolkit designed to package one or more Certificate Revocation Lists (CRLs) into a PKCS#7 structure. A <I>CRL</I> is a list of digital certificates that have been revoked by the Certificate Authority (CA) before their scheduled expiration date, preventing their use.<br><br>PKCS#7, or Cryptographic Message Syntax Standard, defines a general syntax for cryptographic messages, including how to encapsulate signed, enveloped, or digested data, and in this context, how to bundle certificates and CRLs. By converting CRLs to PKCS#7, they can be easily transported, stored, or processed as a single cryptographic object. This is particularly useful in Public Key Infrastructure (PKI) environments for disseminating revocation information efficiently. The command supports various input and output formats, primarily PEM and DER, allowing for flexible integration into different systems and workflows. Its primary role is to create a container for CRLs, sometimes alongside related certificates, for secure and standardized exchange.


title: CAVEATS
content:
The <b>openssl crl2pkcs7</b> command is part of the OpenSSL toolkit; thus, its functionality is dependent on the OpenSSL library's installation and version. Care must be taken to ensure the input CRLs are valid and correctly formatted to avoid processing errors. While <B>-noverify</B> exists, using it bypasses critical security checks and is strongly discouraged in production environments, as it can lead to the acceptance of forged or invalid revocation information. Managing cryptographic keys and certificates, including CRLs, requires a solid understanding of PKI principles.


title: PKCS#7 STRUCTURE
content:
PKCS#7 is a versatile format. When used with <B>crl2pkcs7</B>, it primarily creates a <I>SignedData</I> content type, where the content is a collection of CRLs (and optional certificates). It does not sign the data itself but acts as a container for already signed CRLs.


title: ALTERNATIVE USAGE
content:
For general PKCS#7 creation that includes CRLs, the <B>openssl pkcs7 -crls</B> command can sometimes be used as an alternative or in conjunction, offering broader PKCS#7 manipulation capabilities.


title: HISTORY
content:
The <B>crl2pkcs7</B> functionality is an integral part of the OpenSSL project, which has been under continuous development since its inception as SSLeay in 1995. This command emerged as a necessary tool within the OpenSSL suite to facilitate the management and distribution of Certificate Revocation Lists in a standardized, interoperable format (PKCS#7), crucial for the evolution of Public Key Infrastructure (PKI) and secure communications. Its development has paralleled the increasing adoption of digital certificates and the need for robust revocation mechanisms in web security (HTTPS), secure email (S/MIME), and other cryptographic applications.


title: SEE ALSO
content:
openssl(1): The main OpenSSL command-line tool, of which <B>crl2pkcs7</B> is a subcommand., openssl-crl(1): Utilities for Certificate Revocation List (CRL) management., openssl-pkcs7(1): Utilities for PKCS#7 data manipulation., openssl-x509(1): Certificate display and signing utility, often used in conjunction with CRLs and PKCS#7., pkcs7(5): Man page for the PKCS#7 file format specification.


title: SYNOPSIS
content:
<b>croc</b> [OPTIONS] [FILE | DIRECTORY]<br><b>croc send</b> [OPTIONS] [FILE | DIRECTORY]<br><b>croc receive</b> [OPTIONS] [CODE]<br><b>croc</b> [OPTIONS] [CODE]


title: PARAMETERS
content:
<b>--port <port></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the port for direct connection attempts.<br><br><b>--relay <address></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom relay server address.<br><br><b>--yes</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Automatically accept incoming file transfers without prompt.<br><br><b>--no-compress</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable compression for faster transfers, but larger size.<br><br><b>--stdout</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the received file content to standard output.<br><br><b>--stdin</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read content from standard input to send as a file.<br><br><b>--text <string></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Send a string as a file instead of a local file.<br><br><b>--code <code></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a custom code to use for sending (e.g., 'croc send --code mysecretfile').<br><br><b>--overwrite</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Overwrite existing files at the destination without prompting.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable debug mode for verbose output.<br><br><b>--remember</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Remember custom relay server and port settings for future use.<br><br>


title: DESCRIPTION
content:
<b>croc</b> is a cross-platform command-line tool for secure and simple file transfer between two computers. It allows sending and receiving files or directories with ease, even across NATs, by utilizing a relay server. Files are encrypted end-to-end using PAKE, ensuring privacy. Its primary advantage is its simplicity: a sender generates a unique code, and the receiver uses that code to initiate the transfer. It's ideal for quick, ad-hoc transfers without requiring complex setup, shared keys, or direct IP connections. It supports resuming interrupted transfers and can handle multiple files.


title: CAVEATS
content:
<b>croc</b> relies on a public relay server by default, which might experience heavy load or be blocked in certain networks. While secure via end-to-end encryption, the shared code must be communicated securely out-of-band to prevent unauthorized access. Self-hosting a relay is possible for enhanced control and privacy.


title: HOW IT WORKS
content:
<b>croc</b> operates using a PAKE (Password Authenticated Key Exchange) protocol, specifically <I>PAKE/Curve25519</I>, over a relay server. The sender initiates a transfer, and <b>croc</b> generates a unique, ephemeral code. This code is then shared with the receiver. Both sender and receiver connect to the relay using this code, which acts as a shared secret to establish a secure, encrypted direct connection (if possible via NAT traversal) or tunnel through the relay. The code is only used to establish the connection and derive the encryption key, not for the data itself.


title: HISTORY
content:
Developed in Go by <I>schollz</I> (Zack Scholl), <b>croc</b> gained significant traction for its intuitive approach to file sharing. It emerged as a solution to simplify secure ad-hoc transfers, avoiding the complexities of traditional methods like SSH or setting up dedicated servers. Its cross-platform compatibility and CLI-first design contributed to its rapid adoption by developers and users needing quick data exchange.


title: SYNOPSIS
content:
The <b>cron</b> system itself runs as a daemon and is typically managed by the system's init process. Users interact with the <b>cron</b> system primarily through the <b>crontab</b> command to manage their scheduled jobs.<br><br><b>crontab</b> [<i>-u user</i>] <i>file</i><br><b>crontab</b> [<i>-u user</i>] {<b>-l</b> | <b>-r</b> | <b>-e</b> | <b>-i</b>}


title: PARAMETERS
content:
<b><i>-u user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the user whose crontab is to be edited or viewed. If omitted, the current user's crontab is used.<br><br><b><i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Installs the specified file as the new crontab for the current user (or the user specified with <i>-u</i>).<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists the current crontab content to standard output.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes the current crontab.<br><br><b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Edits the current crontab. This typically opens the crontab in the user's default text editor (e.g., <i>VI</i> or <i>NANO</i>).<br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <i>-r</i> (e.g., <i>crontab -ri</i>) to prompt the user for confirmation before removing the crontab.<br><br>


title: DESCRIPTION
content:
The <b>cron</b> utility is a powerful time-based job scheduler in Unix-like operating systems, including Linux. It allows users to schedule commands or scripts to run automatically at specified intervals. The core of the system is the <b>cron</b> daemon, which runs continuously in the background and checks for scheduled jobs. These jobs are defined in special files called <i>crontab</i> files (short for 'cron table').<br><br>While <b>cron</b> refers to the background service, user interaction for scheduling tasks is typically done via the <b>crontab</b> command. Each user can have their own <i>crontab</i> file, and there is also a system-wide <i>crontab</i> (often located in <i>/etc/crontab</i> or <i>/etc/cron.d/</i>) for system-level tasks. <b>cron</b> ensures that tasks like backups, log rotation, system updates, and custom script execution are performed regularly without manual intervention, making it a fundamental tool for system administration and automation.


title: CAVEATS
content:
<ul><li><b>Environment Variables</b>: <b>cron</b> jobs run in a minimal environment. PATH, HOME, and other variables might not be what you expect. Always use full paths to commands and scripts (e.g., <i>/usr/bin/php</i> instead of <i>php</i>).</li><li><b>Output and Mail</b>: Any output (<i>stdout</i> or <i>stderr</i>) from a <b>cron</b> job is mailed to the user who owns the crontab, unless redirected. This can lead to mailbox clutter if not managed.</li><li><b>Permissions</b>: Users must have appropriate permissions to run commands. The <b>cron</b> daemon runs with specific user permissions.</li><li><b>Syntax Strictness</b>: The <i>crontab</i> file syntax is very specific (minute hour day-of-month month day-of-week command). Errors in syntax can prevent jobs from running.</li><li><b>System-wide vs. User Crontabs</b>: Be aware of the distinction. System-wide crontabs (e.g., in <i>/etc/crontab</i> or <i>/etc/cron.d/</i>) often include a 'user' field that user crontabs do not.</li><li><b>Time Zones</b>: <b>cron</b> jobs typically run based on the system's local time zone settings.</li></ul>


title: CRONTAB FILE FORMAT
content:
Each line in a <i>crontab</i> file represents a single scheduled job and follows a specific format consisting of six fields:<br><i>minute hour day-of-month month day-of-week command-to-execute</i><br><br><ul><li><b>Minute (0-59)</b></li><li><b>Hour (0-23)</b></li><li><b>Day of Month (1-31)</b></li><li><b>Month (1-12 or Jan-Dec)</b></li><li><b>Day of Week (0-7 or Sun-Sat, 0 and 7 are Sunday)</b></li><li><b>Command to Execute</b>: The full command or script to run, including arguments.</li></ul><br>Special characters like <i>*</i> (any value), <i>,</i> (list), <i>-</i> (range), and <i>/</i> (step) can be used. For example, <i>*\/15</i> in the minute field means 'every 15 minutes'.<br>System-wide crontabs (e.g., <i>/etc/crontab</i>) often include an additional field after the <i>day-of-week</i> for the <i>username</i> under which the command should be run.


title: SPECIAL STRINGS FOR SCHEDULING
content:
For common scheduling needs, <b>cron</b> supports several special strings that replace the first five time and date fields:<br><ul><li><b>@reboot</b>: Run once after every reboot.</li><li><b>@yearly</b> or <b>@annually</b>: Run once a year (0 0 1 1 *).</li><li><b>@monthly</b>: Run once a month (0 0 1 * *).</li><li><b>@weekly</b>: Run once a week (0 0 * * 0).</li><li><b>@daily</b> or <b>@midnight</b>: Run once a day (0 0 * * *).</li><li><b>@hourly</b>: Run once an hour (0 * * * *).</li></ul>


title: HISTORY
content:
The concept of scheduled tasks in Unix-like systems dates back to the early days of computing. The name 'cron' is derived from the Greek word 'chronos', meaning time. The original <b>cron</b> daemon was developed by Brian Kernighan at Bell Labs in the late 1970s. Its fundamental design, including the use of <i>crontab</i> files, has remained remarkably consistent over decades, evolving to include features like per-user crontabs and robust error handling. Modern implementations like <i>Vixie cron</i> (developed by Paul Vixie) and <i>ISC cron</i> are widely used, offering improved security and flexibility while maintaining backward compatibility with the classic <b>cron</b> syntax.


title: DESCRIPTION
content:
<b>cronic</b> is a utility from the <b>moreutils</b> package designed to wrap commands, primarily for use within <b>cron</b> jobs. Its core function is to execute a given command and capture its standard output (stdout) and standard error (stderr). By default, <b>cron</b> sends an email whenever a scheduled job produces <i>any</i> output to stdout or stderr, or if it exits with a non-zero status. This can lead to an inbox flooded with emails from successful jobs that produce expected output (e.g., status messages, log entries).<br><br><b>cronic</b> addresses this by only forwarding the captured output (and implicitly, triggering an email from <b>cron</b>) if the wrapped command exits with a non-zero status (indicating failure) OR if it produces any output on stdout or stderr. If the command succeeds and produces no output, <b>cronic</b> suppresses the output, effectively making the cron job silent. This allows administrators to receive notifications only when something unexpected happens – either an error occurs or a job generates significant output that needs attention – greatly reducing mail clutter. It's a small, focused tool that simplifies cron job management by making success silent and failures verbose.


title: CAVEATS
content:
<ul><li><b>Output Buffering:</b> <b>cronic</b> buffers all standard output and standard error until the wrapped command completes. For long-running commands that produce large amounts of output, this can consume significant memory. Additionally, real-time progress updates are not visible until the command finishes or fails.</li><li><b>Exit Status Reliance:</b> It relies solely on the exit status of the wrapped command to determine success (zero exit status) or failure (non-zero exit status). If a command produces unexpected output but still exits with a zero status, <b>cronic</b> will still forward the output.</li><li><b>Not a Scheduler:</b> <b>cronic</b> is a command wrapper, not a cron scheduler or a job management system. It must be invoked from a cron job or similar execution environment.</li></ul>


title: COMMON USAGE EXAMPLE
content:
To run a daily backup script called <i>backup.sh</i> located in <i>/usr/local/bin</i> silently on success but with full output on failure, you would add the following line to your user's crontab (via <code>crontab -e</code>):<br><br><code>0 2 * * * /usr/bin/cronic /usr/local/bin/backup.sh</code><br><br>In this example, <b>cron</b> will execute <b>cronic</b> at 2:00 AM daily. If <i>backup.sh</i> runs successfully and produces no output, <b>cronic</b> will suppress everything, and <b>cron</b> will not send an email. If <i>backup.sh</i> fails (non-zero exit status) or produces any output (e.g., 'Backup completed successfully, 100 files transferred'), <b>cronic</b> will forward that output to <b>cron</b>, triggering an email notification.


title: DISTINCTION FROM <B>SET -E</B>
content:
<b>cronic</b> is often misunderstood as a replacement for shell constructs like <code>set -e</code>. While both deal with errors, their purposes differ. <code>set -e</code> in a shell script causes the script to exit immediately if any command fails (returns a non-zero exit status). <b>cronic</b>, on the other hand, <i>wraps</i> a single command (or an entire script) and only concerns itself with its output and final exit status, relaying output and status <i>after</i> execution. It doesn't modify the internal execution flow of the wrapped command itself.


title: HISTORY
content:
<b>cronic</b> is part of the <b>moreutils</b> package, a collection of useful Unix utilities that extend the functionality of core tools. It emerged as a solution to a common pain point experienced by system administrators: the overwhelming number of emails generated by <b>cron</b> jobs that produce output even when successful. Before <b>cronic</b>, administrators often resorted to redirecting output to <i>/dev/null</i> (e.g., <code>&gt;/dev/null 2&gt;&amp;1</code>) for successful jobs, which meant losing valuable error information in case of failure. <b>cronic</b> provides a simple, elegant mechanism to have the best of both worlds: silence for success, and full output for failures or unexpected output. Its development reflects a pragmatic approach to daily system administration challenges.


title: SYNOPSIS
content:
<i>crontab</i> [<b>-u</b> <i>user</i>] <i>file</i><br><i>crontab</i> [<b>-u</b> <i>user</i>] [<b>-e</b> | <b>-l</b> | <b>-r</b> | <b>-i</b>]


title: PARAMETERS
content:
<b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Edit</i> the current <i>crontab</i> file. If no <i>crontab</i> exists for the user, one is created.<br><br><b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>List</i> the contents of the current <i>crontab</i> file to standard output.<br><br><b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Remove</i> the current <i>crontab</i> file, deleting all scheduled jobs for the user.<br><br><b><b>-i</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompt for confirmation before <i>removing</i> the <i>crontab</i> file (used in conjunction with <b>-r</b>).<br><br><b><b>-u</b> <i>user</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the <i>user</i> whose <i>crontab</i> is to be manipulated. This option is typically restricted to the superuser (root).<br><br><b><i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Install the specified <i>file</i> as the new <i>crontab</i> for the current user. The previous <i>crontab</i> is replaced.<br><br>


title: DESCRIPTION
content:
<i>crontab</i> manages a user's <i>cron</i> table, a file that contains instructions for the <i>cron</i> daemon. The <i>cron</i> daemon is a time-based job scheduler in Unix-like operating systems. By editing your personal <i>crontab</i> file, you can specify commands or scripts to be executed automatically at predefined intervals.<br>This automation is crucial for system administration, data backups, log rotation, and running custom applications at specific times without manual intervention. Each entry in a <i>crontab</i> file consists of five time-and-date fields followed by a command. These fields specify the minute, hour, day of the month, month, and day of the week, allowing for precise control over when a task runs. The <i>crontab</i> command provides an interface to <b>edit</b>, <b>list</b>, and <b>remove</b> these scheduled jobs, ensuring a streamlined process for managing automated tasks specific to your user account. It's distinct from the system-wide <i>cron</i> jobs typically configured in <i>/etc/crontab</i> or <i>/etc/cron.d/</i>.


title: CAVEATS
content:
<b>Environment Variables</b>: <i>crontab</i> jobs execute with a minimal set of environment variables. It's often necessary to explicitly set <i>PATH</i>, <i>SHELL</i>, or other required variables within the <i>crontab</i> file or the executed script.<br><b>Output Handling</b>: Any output from a cron job (stdout or stderr) is typically mailed to the <i>crontab</i> owner by default. For noisy scripts, this can flood mailboxes; consider redirecting output to <i>/dev/null</i> or log files.<br><b>Day of Month vs. Day of Week</b>: A common pitfall is specifying both the 'Day of Month' and 'Day of Week' fields. If both are restricted (not <i>*</i>), the command will execute if <i>either</i> the day of month <i>OR</i> the day of week matches. For example, <i>0 0 1 * 1</i> means 'at midnight on the 1st of every month <i>AND</i> every Monday'.


title: <B>CRONTAB ENTRY FORMAT</B>
content:
Each line in a <i>crontab</i> file (excluding comments and environment settings) defines a single job and consists of six fields:<br><code><i>minute</i> <i>hour</i> <i>day_of_month</i> <i>month</i> <i>day_of_week</i> <i>command_to_execute</i></code><br>The first five fields specify the time and date, accepting numbers, lists (e.g., <i>1,3,5</i>), ranges (e.g., <i>9-17</i>), and step values (e.g., <i>*/5</i> for every 5 minutes). Wildcards (<i>*</i>) represent 'every' value.<br>Additionally, several special strings can replace the first five time fields for convenience:<br><i><b>@reboot</b></i>: Run once after system reboot.<br><i><b>@yearly</b></i> (or <i><b>@annually</b></i>): Run once a year.<br><i><b>@monthly</b></i>: Run once a month.<br><i><b>@weekly</b></i>: Run once a week.<br><i><b>@daily</b></i> (or <i><b>@midnight</b></i>): Run once a day.<br><i><b>@hourly</b></i>: Run once an hour.


title: <B>PERMISSIONS AND ACCESS</B>
content:
The ability to use <i>crontab</i> can be controlled by system-wide configuration files, typically <i>/etc/cron.allow</i> and <i>/etc/cron.deny</i>. If <i>cron.allow</i> exists, only users listed within it may use <i>crontab</i>. If <i>cron.allow</i> does not exist but <i>cron.deny</i> does, users listed in <i>cron.deny</i> are prevented from using <i>crontab</i>. If neither file exists, generally all users can use <i>crontab</i> (though specific distributions may vary).


title: HISTORY
content:
The concept of scheduled tasks, or 'cron' jobs, has been fundamental to Unix-like operating systems since their inception. The <i>cron</i> utility itself was developed at Bell Labs, allowing tasks to be executed periodically. The <i>crontab</i> command emerged as a user-friendly interface to manage personal <i>cron</i> tables. This allowed individual users to define their own scheduled jobs without needing root privileges to modify system-wide cron configurations. Over the years, various <i>cron</i> implementations have evolved, with Vixie cron (now ISC Cron) being a widely adopted standard that influenced much of the <i>crontab</i> functionality seen in modern Linux distributions.


title: PARAMETERS
content:
<b><<i>min_len</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the minimum length of the strings to be generated.</i><br><br><b><<i>max_len</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the maximum length of the strings to be generated.</i><br><br><b><b>-o</b> <<i>filename</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the output file where the generated wordlist will be saved.</i><br><br><b><b>-f</b> <<i>charset.lst</i>> <<i>charset_name</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Loads a predefined character set from a file (e.g., `charset.lst`). You must also specify the name of the character set within that file (e.g., `numeric`, `lowercase`).</i><br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Permutes values, often used in conjunction with patterns to arrange characters in all possible orders.</i><br><br><b><b>-s</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the starting string for the wordlist generation. Generation will begin from this string.</i><br><br><b><b>-e</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the ending string for the wordlist generation. Generation will stop once this string is reached.</i><br><br><b><b>-t</b> <<i>pattern</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Defines a pattern for the generated strings using placeholders: <b>@</b> (lowercase), <b>,</b> (uppercase), <b>%</b> (numeric), <b>^</b> (symbols). Example: <b>-t</b> <i>@@%^</i> for two lowercase, one number, one symbol.</i><br><br><b><b>-d</b> <<i>num</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Limits the number of consecutive duplicate characters allowed in the generated strings.</i><br><br><b><b>-c</b> <<i>lines</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the maximum number of lines (passwords) per output file when splitting the wordlist.</i><br><br><b><b>-z</b> <<i>type</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Compresses the output file using the specified type (e.g., <b>gzip</b>, <b>bzip2</b>, <b>lzma</b>, <b>7z</b>).</i><br><br><b><b>-b</b> <<i>bytes</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the maximum size of the output file in bytes (e.g., 100MB) when splitting the wordlist.</i><br><br><b><b>-q</b> <<i>filename</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Quiet mode: loads character sets from `charset.lst` without displaying internal characters, often used to prevent screen clutter.</i><br><br><b><b>-m</b> <<i>bytes</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Specifies the maximum amount of RAM in bytes that <b>crunch</b> can use during wordlist generation.</i><br><br>


title: DESCRIPTION
content:
<b>Crunch</b> is a powerful and flexible wordlist generator used primarily in security auditing and penetration testing. It allows users to create custom wordlists by specifying minimum and maximum lengths, character sets (alphanumeric, special characters, or custom), and specific patterns. This tool can generate all possible combinations and permutations of characters, making it invaluable for dictionary attacks and brute-force attempts against password hashes or login forms. It supports various output options, including file compression and splitting large wordlists into manageable chunks. Its efficiency and customization options make it a staple for anyone needing to generate targeted dictionaries for security assessments.


title: CAVEATS
content:
<i><br>• Generating large wordlists can consume significant disk space and CPU resources. Always ensure you have sufficient storage and processing power before running <b>crunch</b> for extensive lists.<br>• The ethical use of <b>crunch</b> is crucial; it is intended for authorized penetration testing and security auditing, not for malicious activities.<br>• Without proper options, a seemingly simple command can generate billions of combinations, quickly filling up disk space.</i>


title: CHARACTER SETS
content:
<b>Crunch</b> supports several predefined character sets, including <i>numeric</i> (0-9), <i>lowercase</i> (a-z), <i>uppercase</i> (A-Z), <i>symbols</i> (!@#$%^&*()-_+=~`[]{}\|:;"'<>,./?), and <i>all</i> (a combination of common character types). Users can also define custom character sets directly on the command line or by using the <b>-f</b> option with a `charset.lst` file for more complex or application-specific character requirements.


title: PATTERN GENERATION WITH <B>-T</B>
content:
The <b>-t</b> option allows for highly specific pattern generation, enabling users to define the exact structure of the generated strings. It uses placeholders:<br>• <b>@</b>: <i>Represents a lowercase character (a-z)</i><br>• <b>,</b>: <i>Represents an uppercase character (A-Z)</i><br>• <b>%</b>: <i>Represents a numeric character (0-9)</i><br>• <b>^</b>: <i>Represents a symbol</i><br>For example, `<b>crunch</b> <i>8 8</i> <b>-t</b> <i>@@@@%^^^</i>` would generate 8-character strings starting with four lowercase letters, followed by one number and three symbols. This level of control is invaluable for targeted dictionary attacks.


title: HISTORY
content:
<b>Crunch</b> emerged as a dedicated and highly efficient tool within the information security community, specifically for generating customized dictionaries. Its development was driven by the pervasive need for a robust wordlist generator capable of handling complex character sets and patterns, which is essential for modern password cracking and security auditing techniques. It has become a standard utility in penetration testing distributions like Kali Linux due to its speed, flexibility, and comprehensive feature set.


title: SYNOPSIS
content:
<br><code><B>cryfs</B> &lt;encrypted_dir&gt; &lt;mount_point&gt; [<I>options</I>]</code><br><br><code><B>cryfs</B> --unmount &lt;mount_point&gt;</code><br><br><code><B>cryfs</B> --unmount-all</code><br><br><code><B>cryfs</B> --help</code><br><br><code><B>cryfs</B> --version</code>


title: PARAMETERS
content:
<b>--allow-other</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows users other than the mounter to access the filesystem. Requires <I>user_allow_other</I> in <I>/etc/fuse.conf</I>.<br><br><b>-c <file>, --config <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative configuration file for the CryFS volume.<br><br><b>--cipher-file <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative cipher file for advanced key management.<br><br><b>-f, --foreground</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs CryFS in the foreground; useful for debugging.<br><br><b>-o <options>, --options <options></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes comma-separated FUSE-specific mount options (e.g., <I>ro</I>, <I>default_permissions</I>).<br><br><b>--unmount</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unmounts the specified CryFS volume.<br><br><b>--unmount-all</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Unmounts all currently mounted CryFS volumes.<br><br><b>--volume-key <key></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Provides the volume key directly, bypassing interactive password prompt (use with caution).<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;Prints the CryFS version information and exits.<br><br>


title: DESCRIPTION
content:
CryFS is a free and open-source <I>FUSE (Filesystem in Userspace)</I> based encrypted filesystem. It aims to secure data stored in cloud services by encrypting not only file contents but also metadata like filenames, sizes, and directory structure. Unlike older solutions such as EncFS, CryFS mitigates metadata leaks, providing a higher level of privacy. It works by creating a hidden, encrypted directory (the "root directory") where actual encrypted data resides, and then presenting a decrypted, readable view at a specified "mount point." When files are written to the mount point, CryFS encrypts them and stores the blocks in the root directory. Reading files reverses this process. This makes it a robust solution for protecting sensitive data without relying on the cloud provider's encryption, ensuring that only you can access your information.


title: CAVEATS
content:
<B>Performance Overhead:</B> Encryption and decryption add significant overhead, making CryFS noticeably slower than direct disk access, especially with numerous small files or high I/O.<br><B>Password Security:</B> The strength of your data's protection entirely depends on the robustness of your chosen passphrase. A weak passphrase renders encryption ineffective.<br><B>Proper Unmounting:</B> It is critical to unmount the CryFS volume correctly (e.g., using <I>cryfs --unmount</I> or <I>fusermount -u</I>) before system shutdown or removal of underlying storage. Improper unmounting can lead to data corruption.<br><B>Configuration Files:</B> The <I>cryfs.config</I> file, stored within the encrypted directory, is essential for mounting the volume. Losing or corrupting this file can make your data irrecoverable. Ensure it is backed up if not handled automatically by your cloud sync.<br><B>FUSE Dependency:</B> CryFS relies on the FUSE kernel module and user-space utilities to function, which must be installed and properly configured on the system.


title: <B>INITIAL SETUP</B>
content:
The first time <I>cryfs</I> is run on a new pair of directories, it will interactively prompt for a new passphrase and optionally a salt to create the encrypted filesystem. This passphrase is fundamental for subsequent mounts and data access.


title: <B>USAGE WITH CLOUD SYNC</B>
content:
CryFS is designed to work seamlessly with cloud synchronization tools. You place the encrypted <I>root_dir</I> inside your cloud sync folder (e.g., Dropbox, Google Drive), and mount the decrypted view locally. The cloud service only sees the encrypted data, protecting your privacy.


title: HISTORY
content:
CryFS was developed as a modern, more secure alternative to existing FUSE-based encrypted filesystems, particularly addressing metadata leakage issues found in earlier solutions like EncFS. Development began around 2014-2015, driven by the increasing need for robust data encryption for cloud storage services. Its design focuses on strong cryptographic primitives and a block-based encryption approach to minimize information exposure, ensuring higher privacy by obfuscating file sizes, timestamps, and directory structures. This makes it suitable for environments where an adversary might have access to the raw encrypted data.


title: SYNOPSIS
content:
<b>cryptcat</b> [<i>options</i>] <i>hostname</i> <i>port</i><br><b>cryptcat</b> [<i>options</i>] <b>-l</b> <b>-p</b> <i>port</i>


title: PARAMETERS
content:
<b><b>-l</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Listen mode</i>.<br>Instructs cryptcat to listen for an incoming connection rather than initiating one. This makes cryptcat act as a server.<br><br><b><b>-p</b> <i>&lt;port&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Port</i>.<br>Specifies the local port to listen on when in listen mode (<b>-l</b>), or the remote port to connect to when acting as a client.<br><br><b><b>-k</b> <i>&lt;key&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Key/Passphrase</i>.<br>Defines the shared secret key or passphrase used for Blowfish encryption. If this option is not provided, <b>cryptcat</b> will typically prompt the user to enter the key interactively.<br><br><b><b>-e</b> <i>&lt;program&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Execute program</i>.<br>Executes the specified program after a connection is established. This is commonly used to spawn a shell (e.g., <b>-e /bin/bash</b>) or run a script on the remote end upon connection.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>UDP mode</i>.<br>Forces <b>cryptcat</b> to use UDP (User Datagram Protocol) for communication instead of the default TCP (Transmission Control Protocol).<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Verbose output</i>.<br>Enables verbose mode, causing <b>cryptcat</b> to print more informative messages about the connection process, errors, and status.<br><br><b><b>-n</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Numeric-only IP addresses</i>.<br>Prevents DNS (Domain Name System) lookups for hostnames, forcing <b>cryptcat</b> to use only numeric IP addresses.<br><br><b><b>-w</b> <i>&lt;timeout&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Connection timeout</i>.<br>Specifies a timeout in seconds for connection attempts and for idle connections. If no data is transferred within the timeout period, the connection may be closed.<br><br><b><b>-z</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Zero-I/O mode</i>.<br>Performs a port scan without sending any data to the remote host once a connection is established. This is useful for quickly checking if specific ports are open and listening without initiating a full data transfer.<br><br>


title: DESCRIPTION
content:
<b>cryptcat</b> is a network utility that extends the functionality of the widely-used <b>netcat</b> command by incorporating symmetric Blowfish encryption. It enables users to establish encrypted network connections for various purposes, such as secure data transfer, encrypted shell sessions, or protected port forwarding. <br><br>By requiring a shared passphrase between the communicating parties, <b>cryptcat</b> aims to provide a basic layer of confidentiality for transmitted data, protecting it from passive eavesdropping. It can operate in both client and server modes: as a server, it listens on a specified port, encrypting incoming connections; as a client, it connects to a remote host and port, encrypting outgoing data. While offering a straightforward method for simple encryption, <b>cryptcat</b> is generally considered outdated and insecure for robust protection due to known vulnerabilities in its Blowfish implementation and the absence of proper key exchange mechanisms. Historically, it found use in specific penetration testing scenarios for creating quick, obfuscated network tunnels.


title: CAVEATS
content:
While <b>cryptcat</b> provides a layer of encryption, its security is <I>severely limited</I> and it is <B>not recommended for modern, sensitive communications</B>.<br>The Blowfish implementation within <b>cryptcat</b> is known to have weaknesses, and there's no robust key exchange mechanism, making it highly susceptible to man-in-the-middle attacks if the shared key isn't securely pre-shared through an out-of-band method.<br>It offers <I>no authentication</I> beyond the shared key, meaning anyone with the correct key can connect.<br>For any serious security requirement, <I>SSH</I> or other modern, strong encryption protocols are vastly superior and should always be used instead.


title: <I>SECURITY WARNING</I>
content:
Due to known vulnerabilities in its encryption implementation and the inherent weaknesses of a simple shared-key system without proper key exchange or authentication, <I>cryptcat</I> is <B>not recommended</B> for secure communications in production or sensitive environments. Users should always prefer modern, robust alternatives like <I>SSH</I> for encrypted data transfer and remote access.


title: <I>COMPARISON WITH NETCAT</I>
content:
<I>cryptcat</I> is essentially a modified version of <I>netcat</I>. It retains most of <I>netcat</I>'s options and functionality for network connectivity (listening, connecting, port scanning, executing programs), but adds the encryption layer on top of the raw data stream. This means anything that can be done with <I>netcat</I> can generally be attempted with <I>cryptcat</I>, with the added (though limited) benefit of encryption. The command-line syntax and behavior are largely interchangeable with <i>netcat</i>, making it easy for users familiar with <i>netcat</i> to adopt <i>cryptcat</i>.


title: HISTORY
content:
<b>cryptcat</b> emerged as a utility combining the versatile networking capabilities of <I>netcat</I> with a simple encryption layer using the Blowfish algorithm. It gained some popularity in the late 1990s and early 2000s, particularly within the information security and penetration testing communities, as a quick way to establish somewhat obfuscated or encrypted tunnels over networks. It filled a niche before the widespread adoption and standardization of more robust secure shell solutions like <I>SSH</I>. Its development was not as formal or continuously maintained as core system utilities, often appearing in various security toolkits and distributions as a specialized tool for specific scenarios.


title: PARAMETERS
content:
<b><I>DEVICE</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a particular encrypted device name as defined in `<b>/etc/crypttab</b>` to activate. If omitted, `<b>cryptdisks_start</b>` attempts to activate all entries listed in `<b>crypttab</b>`.<br><br>


title: DESCRIPTION
content:
The `<b>cryptdisks_start</b>` command is a crucial script or utility primarily used on Linux systems (especially Debian/Ubuntu derivatives) to manage and activate encrypted block devices during system startup or on demand. It plays a vital role in enabling access to data on encrypted partitions or full disks that use LUKS (Linux Unified Key Setup).<br><br>It primarily works by reading the configuration from the `<b>/etc/crypttab</b>` file. This file specifies details for each encrypted volume, including the device name, the underlying physical device, the key material (e.g., a passphrase, a keyfile, or `<b>none</b>` for interactive prompt), and various options to be passed to the underlying `<b>cryptsetup</b>` utility.<br><br>For each specified encrypted device, `<b>cryptdisks_start</b>` invokes the `<b>cryptsetup</b>` utility to decrypt the volume and create a corresponding unencrypted device mapper entry (e.g., `<b>/dev/mapper/myencryptedvolume</b>`). This process ensures that filesystems residing on encrypted volumes, such as root (`<b>/</b>`), swap, or home directories, are accessible to the operating system after decryption.<br><br>The command is typically invoked automatically during the system's boot sequence by `<b>systemd</b>` units or older `<b>init</b>` scripts, especially within the `<b>initramfs</b>` environment, to enable access to encrypted root filesystems.


title: CAVEATS
content:
Incorrect entries in `<b>/etc/crypttab</b>` can lead to system boot failures or inaccessible partitions.<br>The command relies heavily on the correct functioning and presence of the `<b>cryptsetup</b>` utility.<br>Using incorrect passphrases or keyfiles will prevent decryption and volume activation.<br>For interactive password prompts during early boot, user intervention is required, which can halt the boot process.


title: CONFIGURATION FILE: /ETC/CRYPTTAB
content:
This file is central to `<b>cryptdisks_start</b>`'s operation. It lists encrypted devices to be activated, their underlying block devices, the key material (e.g., `<b>none</b>` for password prompt, a path to a keyfile), and various options passed directly to `<b>cryptsetup</b>`. Each line represents one encrypted volume.


title: EARLY BOOT INTEGRATION
content:
`<b>cryptdisks_start</b>` is frequently run during the early stages of the boot process, often from within the `<b>initramfs</b>`. This is crucial for systems with an encrypted root filesystem, as it allows the root volume to be decrypted and mounted before the main operating system fully loads. It can also be used to activate other encrypted volumes later in the boot process or on demand.


title: HISTORY
content:
Initially part of early `<b>init</b>` scripts and `<b>sysvinit</b>` configurations for managing encrypted volumes, `<b>cryptdisks_start</b>` evolved alongside the adoption of LUKS for disk encryption. Its primary function remains consistent: to automate the activation of encrypted devices during system startup. With the transition to `<b>systemd</b>`, its invocation methods adapted to `<b>systemd</b>` service units, but the underlying logic and reliance on `<b>/etc/crypttab</b>` and `<b>cryptsetup</b>` persist. It is often included in the `<b>initramfs</b>` to handle encrypted root filesystems.


title: PARAMETERS
content:
<b><I>device_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <B>logical name</B> of the encrypted device to stop. This name typically corresponds to an entry in <I>/etc/crypttab</I> or the name under <I>/dev/mapper/</I> that represents the active encrypted volume.<br><br>


title: DESCRIPTION
content:
<B>cryptdisks_stop</B> is a crucial command within the Linux disk encryption ecosystem, primarily used to securely deactivate an active encrypted volume. Often found as a helper script or service on Debian/Ubuntu-based distributions, it acts as a high-level wrapper, typically invoking underlying <B>cryptsetup luksClose</B> commands.<br><br>Its main purpose is to close the encrypted device, preventing further access to the data until it is reactivated with the correct passphrase. This command is vital during system shutdown to ensure all encrypted volumes are properly detached, or when manually deactivating a volume after use. Before running <B>cryptdisks_stop</B>, it is paramount that all filesystems residing on the encrypted device are unmounted using the <B>umount</B> command. Failure to unmount can lead to data corruption or loss.<br><br><B>cryptdisks_stop</B> takes the logical name of the encrypted device (e.g., <I>my_encrypted_volume</I> from <I>/etc/crypttab</I>) as an argument, closing the corresponding <I>/dev/mapper/</I> entry. It contributes to maintaining data integrity and security by ensuring clean disengagement of encrypted storage.


title: CAVEATS
content:
<ul><li>It is <B>absolutely critical</B> to unmount any filesystems mounted on the encrypted device <I>before</I> attempting to stop it with <B>cryptdisks_stop</B>. Failure to do so can lead to severe data corruption or loss.</li><li>The command requires <B>root privileges</B> to execute successfully.</li><li>The command will fail if the specified <I>device_name</I> is not an active encrypted device or if it is still in use (e.g., open files, active processes).</li></ul>


title: INTEGRATION WITH SYSTEM SHUTDOWN
content:
On systems configured with encrypted volumes defined in <I>/etc/crypttab</I>, <B>cryptdisks_stop</B> is often invoked automatically as part of the system shutdown process. This ensures that all active encrypted volumes are securely closed before the system powers off, preventing data inconsistencies or unauthorized access.


title: MANUAL DEACTIVATION WORKFLOW
content:
To manually deactivate an encrypted volume (e.g., one activated with <B>cryptdisks_start</B> or <B>cryptsetup luksOpen</B>), the typical workflow involves:<br><br>1. <B>Identify</B> the mounted filesystem(s) on the encrypted device.<br>2. <B>Unmount</B> all filesystems using <B>umount</B>.<br>3. <B>Stop</B> the encrypted device using <B>cryptdisks_stop</B> <I>device_name</I>.


title: HISTORY
content:
<B>cryptdisks_stop</B>, along with <B>cryptdisks_start</B>, emerged as part of the <B>cryptsetup</B> utilities package, primarily on Debian and Ubuntu-based distributions. These scripts were historically used by traditional init systems (e.g., <I>/etc/init.d/cryptdisks</I>) to manage encrypted volumes during system boot and shutdown. With the adoption of <B>systemd</B>, their role often transitioned to being called by <B>systemd-cryptsetup</B> services or serving as wrappers for <B>cryptsetup</B> commands, maintaining a consistent high-level interface for users and administrators. Their development has been integral to the secure and automated management of <B>dm-crypt</B> and <B>LUKS</B> encrypted storage in Linux.


title: SEE ALSO
content:
<B>cryptsetup(8)</B>: The underlying utility used for managing LUKS encrypted devices., <B>crypttab(5)</B>: The configuration file that defines encrypted volumes to be activated during system boot., <B>cryptdisks_start(8)</B>: The counterpart command used to activate encrypted disk devices., <B>mount(8)</B>: Used to attach filesystems to the file hierarchy., <B>umount(8)</B>: Used to detach filesystems from the file hierarchy., <B>systemd-cryptsetup(8)</B>: For systems using systemd, this unit manages encrypted volumes.


title: SYNOPSIS
content:
<b>cryptsetup</b> [<i>OPTIONS</i>] <i>&lt;command&gt;</i> <i>&lt;device&gt;</i> [<i>&lt;name&gt;</i>] [<i>&lt;args&gt;</i>...]<br><br><i>Common invocation examples:</i><br><b>cryptsetup</b> <b>luksFormat</b> <i>&lt;device&gt;</i><br><b>cryptsetup</b> <b>open</b> <i>&lt;device&gt;</i> [<i>&lt;name&gt;</i>] [<i>--type &lt;type&gt;</i>]<br><b>cryptsetup</b> <b>close</b> <i>&lt;name&gt;</i>


title: PARAMETERS
content:
<b>--verbose, -v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show more detailed information during command execution.<br><br><b>--debug, -d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show debug messages for problem diagnosis.<br><br><b>--quiet, -q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress all non-error messages.<br><br><b>--batch-mode, -y</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Never ask for user input. Operations requiring input will fail.<br><br><b>--tries <num>, -S <num></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the number of tries for password input.<br><br><b>--timeout <seconds>, -T <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the timeout for password input in seconds.<br><br><b>--cipher <cipher>, -c <cipher></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the encryption cipher and mode (e.g., <i>aes-xts-plain64</i>).<br><br><b>--hash <hash>, -h <hash></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the hash algorithm (e.g., <i>sha256</i>) for PBKDF.<br><br><b>--key-size <bytes>, -s <bytes></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the encryption key size in bits for the master key.<br><br><b>--iter-time <milliseconds>, -i <milliseconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;PBKDF iteration time for passphrase processing in milliseconds.<br><br><b>--key-file <file>, -l <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Read the key (passphrase or binary key) from the specified file instead of stdin.<br><br><b>--pbkdf <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the PBKDF algorithm to use (e.g., <i>argon2i</i>, <i>pbkdf2</i>).<br><br><b>--pbkdf-memory-cost <num></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Memory cost for PBKDF (e.g., Argon2). Higher values provide better security but require more RAM.<br><br><b>--header-backup-file <file></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a file for LUKS header backup or restore operations.<br><br><b>--allow-discards</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enable TRIM/DISCARD support for the mapped device. Can have security implications.<br><br><b>--type <type></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the type of encrypted device (e.g., <i>luks</i>, <i>plain</i>, <i>veracrypt</i>).<br><br>


title: DESCRIPTION
content:
<b>cryptsetup</b> is a powerful command-line utility used to manage encrypted block devices, primarily leveraging the <i>dm-crypt</i> kernel module and the <b>LUKS</b> (Linux Unified Key Setup) on-disk format. It provides a user-friendly frontend to <i>dm-crypt</i>, simplifying complex encryption tasks.<br><br>Its main purpose is to create, open, close, and manage <b>LUKS</b> encrypted volumes, which are widely used for full disk encryption, encrypted partitions, and portable storage devices. <b>LUKS</b> offers a standardized way to store encryption metadata, allowing for multiple passphrases/keys for the same volume, passphrase revocation, and effective key management.<br><br><b>cryptsetup</b> also supports plain <i>dm-crypt</i> (without <b>LUKS</b> header), <i>TrueCrypt</i>/<i>VeraCrypt</i> compatible volumes, and <i>loop-AES</i> volumes. It does not handle filesystem operations directly but rather provides an unencrypted block device on top of an encrypted one, which can then be formatted and mounted like any other disk. It is an essential tool for data security and privacy on Linux systems.


title: CAVEATS
content:
Using <b>cryptsetup</b> incorrectly can lead to irreversible data loss. Always back up important data, especially the <b>LUKS</b> header, before performing any operations that modify the encryption metadata or the device itself. Strong passphrases and robust PBKDF parameters are crucial for security. Be aware that <b>cryptsetup</b> operates on block devices; it does not manage filesystems directly. Performance can be impacted by the chosen cipher, key size, and underlying hardware. Enabling TRIM/DISCARD (<i>--allow-discards</i>) can have security implications by revealing data patterns if not handled carefully, potentially making erased data recoverable by an attacker.


title: COMMON COMMANDS/ACTIONS
content:
<b>cryptsetup</b> is an action-oriented command-line tool. Here are some of its most commonly used commands:<br><ul><li><b>luksFormat</b>: Formats a device with a new <b>LUKS</b> header and sets an initial passphrase. This is the first step to create an encrypted volume.</li><li><b>open</b> <i>&lt;device&gt;</i> [<i>&lt;name&gt;</i>]: Opens an encrypted device (<b>LUKS</b> or plain) and maps it to a decrypted device-mapper name (e.g., <i>/dev/mapper/&lt;name&gt;</i>). This decrypted device can then be used for filesystem creation and mounting.</li><li><b>close</b> <i>&lt;name&gt;</i>: Closes an opened encrypted device, removing its mapping from <i>/dev/mapper</i>.</li><li><b>luksAddKey</b>: Adds a new passphrase or key to a <b>LUKS</b> volume.</li><li><b>luksRemoveKey</b>: Removes an existing passphrase or key from a <b>LUKS</b> volume.</li><li><b>luksDump</b>: Displays information about the <b>LUKS</b> header, including key slots, UUID, and encryption parameters.</li><li><b>luksHeaderBackup</b>: Backs up the <b>LUKS</b> header to a file. Crucial for recovery in case of header corruption.</li></ul>


title: LUKS HEADER IMPORTANCE
content:
The <b>LUKS</b> header contains all critical metadata for accessing the encrypted data, including encryption parameters (cipher, key size, hash), key slot information, and encrypted master keys. Without a valid and intact <b>LUKS</b> header, the data on the encrypted volume is irrecoverable. Regular backups of the <b>LUKS</b> header are highly recommended using <i>luksHeaderBackup</i> to protect against accidental corruption or deletion.


title: PASSPHRASE SECURITY AND PBKDF
content:
The security of a <b>LUKS</b> volume heavily relies on the strength of its passphrases and the parameters used for the Password-Based Key Derivation Function (PBKDF). <b>cryptsetup</b> allows configuration of PBKDF parameters like <i>iter-time</i> (iterations), <i>pbkdf-memory-cost</i> (memory usage, especially for Argon2), and <i>pbkdf-parallel-threads</i>. Modern <b>cryptsetup</b> versions default to Argon2, which is more resistant to brute-force attacks than older PBKDF2 due to its memory-hard and time-hard properties. Users should choose strong, unique passphrases and ensure PBKDF parameters are adequately configured for their security needs.


title: HISTORY
content:
<b>cryptsetup</b> originated as a user-friendly front-end to the <i>dm-crypt</i> kernel module, which provides transparent encryption of block devices. The <i>dm-crypt</i> project itself was created in 2002. <b>cryptsetup</b> was developed to simplify the often complex setup and management of <i>dm-crypt</i> volumes. A significant milestone was the adoption and robust support for the <b>LUKS</b> (Linux Unified Key Setup) standard, developed in 2004 by Clemens Fruhwirth. <b>LUKS</b> provided a standardized on-disk format for encrypted volumes, enabling multi-user key management, key revocation, and improved interoperability across Linux distributions. This standardization greatly enhanced the usability and security of encrypted volumes, making <b>cryptsetup</b> and <b>LUKS</b> the de-facto standard for disk encryption on Linux.


title: PARAMETERS
content:
<b><i>&lt;device&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The block device or partition to be formatted with LUKS (e.g., <i>/dev/sdb1</i>).<br><br><b><b>-y</b>, <b>--verify-passphrase</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prompts for passphrase verification by asking for it twice.<br><br><b><b>--type</b> <i>&lt;type&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the LUKS header type. Commonly <i>luks1</i> or <i>luks2</i>. Default is <i>luks2</i> for modern cryptsetup versions.<br><br><b><b>-s</b>, <b>--key-size</b> <i>&lt;bits&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the master key size in bits (e.g., 256, 512). The default depends on the chosen cipher.<br><br><b><b>-h</b>, <b>--hash</b> <i>&lt;algo&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the hash algorithm for passphrase hashing (e.g., <i>sha256</i>, <i>sha512</i>).<br><br><b><b>-i</b>, <b>--iter-time</b> <i>&lt;ms&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired PBKDF iteration time in milliseconds. A higher value increases passphrase resistance to brute-force attacks by increasing the time to unlock.<br><br><b><b>-c</b>, <b>--cipher</b> <i>&lt;algo&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the cipher algorithm (e.g., <i>aes</i>, <i>serpent</i>, <i>twofish</i>). Often combined with <i>--cipher-mode</i>.<br><br><b><b>--cipher-mode</b> <i>&lt;mode&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the cipher mode (e.g., <i>cbc-essiv</i>, <i>xts-plain64</i>). Usually paired with <i>--cipher</i>. <i>xts-plain64</i> is common for disk encryption.<br><br><b><b>--pbkdf</b> <i>&lt;algo&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PBKDF algorithm (e.g., <i>argon2i</i>, <i>pbkdf2</i>). <i>argon2i</i> is the default for LUKS2, offering better security than PBKDF2.<br><br><b><b>--header</b> <i>&lt;file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stores the LUKS header in a separate file instead of on the device itself. This can be useful for specific setups or plausible deniability.<br><br><b><b>--align-payload</b> <i>&lt;sectors&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Aligns the start of the encrypted payload to a specific sector boundary, which can improve performance on some storage devices, especially SSDs.<br><br>


title: DESCRIPTION
content:
The command <b>cryptsetup luksFormat</b> (often colloquially referred to as <i>cryptsetup-luksformat</i>) is used to initialize a block device or a partition with the LUKS (Linux Unified Key Setup) encryption standard. LUKS provides a standard on-disk format for encrypted volumes, enabling compatibility between different tools and distributions.<br><br>When executed, <b>cryptsetup luksFormat</b> prompts the user to enter a passphrase, which is then used to derive master keys for encryption. It securely generates random master keys and stores them, along with the passphrase hash and PBKDF (Password-Based Key Derivation Function) parameters, in a LUKS header at the beginning of the device. This header also contains metadata about the encryption, such as the cipher algorithm and key size.<br><br>LUKS supports up to eight different 'key slots', allowing multiple passphrases or key files to unlock the same encrypted device. This feature is highly beneficial for scenarios requiring multiple users or enabling key revocation.<br><br>It's crucial to understand that running <b>cryptsetup luksFormat</b> is a destructive operation: it overwrites the existing data on the specified device. Therefore, it should only be used on new devices or devices where all existing data has been backed up or is no longer needed. After formatting, the device must be 'opened' (using <b>cryptsetup open</b>) and then typically formatted with a filesystem (e.g., ext4, XFS) before it can be used for data storage.


title: CAVEATS
content:
<b>Data Destruction:</b> Running <b>cryptsetup luksFormat</b> is a highly destructive operation that will irreversibly erase all existing data on the specified device. Always double-check the target device and ensure all critical data is backed up before proceeding.<br><br><b>Passphrase Security:</b> The overall security of your encrypted volume is directly dependent on the strength and secrecy of your passphrase. Choose a long, complex, and unique passphrase that is not easily guessable.<br><br><b>LUKS Header Backup:</b> The LUKS header contains crucial metadata. If it becomes corrupted or lost, your data may become inaccessible. It is strongly recommended to back up the LUKS header after formatting using the <b>cryptsetup luksHeaderBackup</b> command.<br><br><b>PBKDF Parameters:</b> While default PBKDF parameters are often sensible, custom tuning (e.g., <i>--iter-time</i> for PBKDF2, or <i>--pbkdf-memory</i> and <i>--pbkdf-parallel</i> for Argon2) can significantly enhance resistance against brute-force attacks, though it will increase the time it takes to unlock the volume.


