koji-cancel

Cancel a task by its ID

$ koji cancel [task_id]

$ koji cancel [task_id1 task_id2 ...]

$ koji cancel --verbose [task_id]

$ koji cancel [[-h|--help]]

koji-cancel [options] <TASK_ID> [<TASK_ID> ...]
koji-cancel [options] --tag <TAG_NAME>

--help, -h
    Show a help message and exit.

--debug, -d
    Print debugging output for verbose operations.

--quiet, -q
    Do not print status messages during execution.

--tag <TAG_NAME>
    Cancel all tasks associated with a specific Koji tag.

--force, -f
    Do not prompt for confirmation when canceling tasks, especially when using the --tag option.

--hub <URL>
    Specify the URL of the Koji hub to connect to. Overrides the default configured hub.

--weburl <URL>
    Specify the URL of the Koji web interface. Overrides the default configured URL.

--config <FILE>
    Use the specified configuration file instead of the default.

--session <FILE>
    Use a specified session file for authentication, typically for existing authenticated sessions.

--user <USERNAME>
    Specify the Koji username for authentication.

--password <PASSWORD>
    Specify the Koji password for authentication. Not recommended for interactive use due to security concerns.

--keytab <FILE>
    Specify the Kerberos keytab file to use for authentication.

--principal <PRINCIPAL>
    Specify the Kerberos principal to use for authentication.

Koji is a distributed build system primarily used by Fedora and Red Hat for building RPM packages and other software artifacts. The `koji-cancel` command provides a mechanism to terminate or abort ongoing tasks within the Koji system. This is crucial for managing build resources, stopping erroneous builds, or halting tasks that are no longer needed.

When invoked, `koji-cancel` communicates with the Koji hub to mark specified tasks as 'canceled'. This action prevents the task from progressing further and frees up build resources. Users typically cancel tasks by their unique integer task ID. It's also possible to cancel all tasks associated with a particular build tag, though this is a more aggressive operation. The command requires appropriate Koji user permissions to execute a cancel operation.

Permissions: Users must have appropriate Koji permissions (e.g., admin or cancel permission) to cancel tasks. Unauthorized attempts will fail.

Irreversibility: Once a task is canceled, it cannot be resumed. A new task must be submitted if the build is still desired.

Timing: A task might not be immediately canceled if it's already in a critical stage or nearing completion. The Koji builder client still needs to acknowledge and process the cancellation request.

Resource Release: While cancellation stops a task, it may take some time for associated resources (e.g., build roots, chroots) to be fully cleaned up and released by the builder.

The `koji-cancel` command typically exits with `0` on success and a non-zero value on error. Non-zero values indicate issues such as tasks not found, authentication failures, insufficient permissions, or network problems.

Koji client commands, including `koji-cancel`, often rely on configuration files (e.g., `~/.koji/config` or `/etc/koji.conf`) to define default hub URLs, authentication methods, and other settings. This reduces the need for explicit command-line options for common operations.

The Koji build system was originally developed by Red Hat as the successor to the `mock` and `pungi` tools, becoming the official build system for Fedora. The `koji-cancel` command has been a fundamental part of the Koji client utility suite since the early stages of Koji's development. Its necessity arose from the need to manage and control numerous build tasks running concurrently across distributed builders, allowing administrators and authorized users to respond to build failures, resource contention, or changing priorities efficiently. The command's core functionality has remained consistent, evolving alongside the broader Koji system and its authentication mechanisms (e.g., Kerberos support).

koji(1), koji-build(1), koji-watch-task(1), koji-list-tasks(1), koji-taskinfo(1)