Skip to content

Introduces immutability to IPP-USB OCI image #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 9 commits into
base: master
Choose a base branch
from
Open

Introduces immutability to IPP-USB OCI image #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7b25692
Introducing immutability to IPP-USB OCI image
im0vishal Mar 19, 2025
44b2745
Updated ReadMe to include runtime flags for data persistence
im0vishal Mar 19, 2025
3d84e40
Updated documentation for configuration and logging setup
im0vishal Mar 20, 2025
f936a9b
Include nano in Rock image and improve docs with persistent storage f…
im0vishal Mar 20, 2025
b932a99
Updated Documentation and Rockcraft file
im0vishal Mar 20, 2025
a4090b0
Enhanced persistence: Separate volumes for state, config, and logs in…
im0vishal Mar 22, 2025
0fde002
Updated run-ipp-usb script
im0vishal Mar 22, 2025
ba720d2
Merge branch 'OpenPrinting:master' into immutable-ipp-usb
im0vishal Apr 29, 2025
0bfca65
Merge branch 'OpenPrinting:master' into immutable-ipp-usb
im0vishal Apr 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 175 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,76 +235,123 @@ start ipp-usb when needed.
sudo snap install docker
```

#### Step-by-Step Guide
#### **Running the `ipp-usb` Container with Persistent Storage**

You can pull the `ipp-usb` Docker image from the GitHub Container Registry.
To run the `ipp-usb` container while ensuring that its state persists across restarts, follow these steps.

**From GitHub Container Registry** <br>
To pull the image from the GitHub Container Registry, run the following command:
#### **1. Pull the `ipp-usb` Docker Image**
The latest image is available on the GitHub Container Registry. Pull it using:
```sh
sudo docker pull ghcr.io/openprinting/ipp-usb:latest
sudo docker pull ghcr.io/openprinting/ipp-usb:latest
```

To run the container after pulling the image, use:
#### **2. Create Persistent Storage Volumes**
To ensure that configuration settings and printer state persist across container restarts, create two Docker volumes:

```sh
sudo docker run -d --network host \
-v /dev/bus/usb:/dev/bus/usb:ro \
--device-cgroup-rule='c 189:* rmw' \
--name ipp-usb \
ghcr.io/openprinting/ipp-usb:latest
```
sudo docker volume create ipp-usb-state
sudo docker volume create ipp-usb-conf
```

These volumes store:

- `--network host`: Uses the host network, ensuring IPP-over-USB and Avahi service discovery work correctly.
- `-v /dev/bus/usb:/dev/bus/usb:ro`: Grants the container read-only access to USB devices.
- `--device-cgroup-rule='c 189:* rmw'`: Grants the container permission to manage USB devices (189:* covers USB device nodes).
- **`ipp-usb-state` (`/var/ipp-usb/`)**
- Device state files (`/var/ipp-usb/dev/`) – Ensures stable TCP port allocation and DNS-SD name resolution.
- Lock files (`/var/ipp-usb/lock/`) – Prevents multiple instances from running simultaneously.
- Log files (`/var/log/ipp-usb/`) – Can be optionally mounted if needed for debugging.

- **`ipp-usb-conf` (`/etc/ipp-usb/`)**
- Configuration file (`/etc/ipp-usb/ipp-usb.conf`) – Stores user-defined settings.
- Quirks files (`/etc/ipp-usb/quirks/`) – Contains printer-specific workarounds.

#### **3. Run the Container with Required Mounts**
Start the container with appropriate options:

To check the logs of `ipp-usb`, run:
```sh
sudo docker logs -f ipp-usb
sudo docker run -d --network host \
-v /dev/bus/usb:/dev/bus/usb:ro \
-v ipp-usb-state:/var/ipp-usb \
-v ipp-usb-conf:/etc/ipp-usb \
--device-cgroup-rule='c 189:* rmw' \
--name ipp-usb \
ghcr.io/openprinting/ipp-usb:latest
```

- **`--network host`** → Uses the host’s network to enable proper IPP-over-USB and Avahi service discovery.
- **`-v /dev/bus/usb:/dev/bus/usb:ro`** → Grants read-only access to USB devices for printer detection.
- **`-v ipp-usb-state:/var/ipp-usb`** → Mounts the persistent storage volume for printer state, lock files, and logs.
- **`-v ipp-usb-conf:/etc/ipp-usb`** → Ensures configuration and quirks files persist across reboots.
- **`--device-cgroup-rule='c 189:* rmw'`** → Grants read, write, and management permissions for USB printers inside the container.


### Building and Running `ipp-usb` Locally

#### Prerequisites

**Docker Installed**: Ensure Docker is installed on your system. You can download it from the [official Docker website](https://www.docker.com/get-started) or from the Snap Store:
1. **Docker Installed**: Ensure Docker is installed on your system. You can download it from the [official Docker website](https://www.docker.com/get-started) or from the Snap Store:
```sh
sudo snap install docker
```

**Rockcraft**: Rockcraft should be installed. You can install Rockcraft using the following command:
2. **Rockcraft**: Rockcraft should be installed. You can install Rockcraft using the following command:
```sh
sudo snap install rockcraft --classic
```

#### Step-by-Step Guide

**Build the `ipp-usb` Rock Image**
**To Build and Run the `ipp-usb` Rock Image Locally, follow these steps**

The first step is to build the Rock from the `rockcraft.yaml`. This image will contain all the configurations and dependencies required to run `ipp-usb`.
#### **1. Build the `ipp-usb` Rock Image**
The first step is to build the Rock image from the `rockcraft.yaml` configuration file. This image will include all required dependencies and configurations for `ipp-usb`.

Navigate to the directory containing `rockcraft.yaml`, then run:
Navigate to the directory containing `rockcraft.yaml` and run:
```sh
rockcraft pack -v
```
```

**Compile to Docker Image**
#### **2. Convert the Rock Image to a Docker Image**
Once the `.rock` file is built, convert it into a Docker image using:
```sh
sudo rockcraft.skopeo --insecure-policy copy oci-archive:<rock_image> docker-daemon:ipp-usb:latest
```

#### **3. Create Persistent Storage Volumes**
To ensure that configuration settings and printer state persist across container restarts, create two Docker volumes:

Once the `.rock` file is built, compile a Docker image from it using:
```sh
sudo rockcraft.skopeo --insecure-policy copy oci-archive:<rock_image_name> docker-daemon:ipp-usb:latest
```
sudo docker volume create ipp-usb-state
sudo docker volume create ipp-usb-conf
```

**Run the `ipp-usb` Docker Container**
These volumes store:

- **`ipp-usb-state` (`/var/ipp-usb/`)**
- Device state files (`/var/ipp-usb/dev/`) – Ensures stable TCP port allocation and DNS-SD name resolution.
- Lock files (`/var/ipp-usb/lock/`) – Prevents multiple instances from running simultaneously.
- Log files (`/var/log/ipp-usb/`) – Can be optionally mounted if needed for debugging.

- **`ipp-usb-conf` (`/etc/ipp-usb/`)**
- Configuration file (`/etc/ipp-usb/ipp-usb.conf`) – Stores user-defined settings.
- Quirks files (`/etc/ipp-usb/quirks/`) – Contains printer-specific workarounds.

#### **4. Run the Container with Required Mounts**
Start the container with appropriate options:

```sh
sudo docker run -d --network host \
-v /dev/bus/usb:/dev/bus/usb:ro \
--device-cgroup-rule='c 189:* rmw' \
--name ipp-usb \
ipp-usb:latest
sudo docker run -d --network host \
-v /dev/bus/usb:/dev/bus/usb:ro \
-v ipp-usb-state:/var/ipp-usb \
-v ipp-usb-conf:/etc/ipp-usb \
--device-cgroup-rule='c 189:* rmw' \
--name ipp-usb \
ipp-usb:latest
```

- **`--network host`** → Uses the host’s network to enable proper IPP-over-USB and Avahi service discovery.
- **`-v /dev/bus/usb:/dev/bus/usb:ro`** → Grants read-only access to USB devices for printer detection.
- **`-v ipp-usb-state:/var/ipp-usb`** → Mounts the persistent storage volume for printer state, lock files, and logs.
- **`-v ipp-usb-conf:/etc/ipp-usb`** → Ensures configuration and quirks files persist across reboots.
- **`--device-cgroup-rule='c 189:* rmw'`** → Grants read, write, and management permissions for USB printers inside the container.

### Accessing the Container Shell

To enter the running `ipp-usb` container and access a shell inside it, use:
Expand All @@ -313,22 +360,105 @@ To enter the running `ipp-usb` container and access a shell inside it, use:
```
This allows you to inspect logs, debug issues, or manually run commands inside the container.

### Configuration
### Configuration

The `ipp-usb` container uses a configuration file located at:
The `ipp-usb` container uses a configuration file located at:
```sh
/etc/ipp-usb/ipp-usb.conf
```
/etc/ipp-usb.conf
By default, the container uses the built-in configuration, which can be modified from inside the container.

**Modifying the Configuration File Inside the Container**

#### **1. Enter the Running Container**
Use the following command to access the container’s shell:
```sh
sudo docker exec -it ipp-usb bash
```
To customize the configuration, mount a modified config file:

#### **2. Open the Configuration File in Nano**
Once inside the container, open the configuration file using `nano`:
```sh
sudo docker run -d --network host \
-v /dev/bus/usb:/dev/bus/usb:ro \
--device-cgroup-rule='c 189:* rmw' \
-v /path/to/custom/ipp-usb.conf:/etc/ipp-usb.conf:ro \
--name ipp-usb \
ghcr.io/openprinting/ipp-usb:latest
nano /etc/ipp-usb/ipp-usb.conf
```

#### **3. Edit and Save the File**
- Make the necessary changes to the file.
- Press `CTRL + X`, then `Y`, and hit `Enter` to save the changes.

#### **4. Restart the Container to Apply Changes**
Exit the container and restart it to apply the updated configuration:
```sh
sudo docker restart ipp-usb
```

### **Viewing Logs in the `ipp-usb` Container**

The `ipp-usb` container logs important events and errors to `/var/log/ipp-usb/`. Logs are categorized into:

- **Main log file:** `/var/log/ipp-usb/main.log` → Captures overall service activity, including errors and general events.
- **Per-device logs:** `/var/log/ipp-usb/<DEVICE>.log` → Individual log files for each detected printer, helpful for troubleshooting device-specific issues.

#### **1. Using Docker Logs**

To view real-time logs from the running container, use:
```sh
sudo docker logs -f ipp-usb
```
- The `-f` flag follows the logs in real-time.
- Replace `ipp-usb` with your actual container name if different.

#### **2. Viewing Logs Inside the Container**

If you need to inspect logs manually, first enter the container shell:
```sh
sudo docker exec -it ipp-usb bash
```

Once inside the container, you can use the following commands:

#### **2.1 Monitor Logs in Real-Time**

- **Main log file:**
```sh
tail -f /var/log/ipp-usb/main.log
```
This continuously displays new log entries for the entire service.

- **Per-device log file (Replace `<DEVICE>` with your printer's identifier):**
```sh
tail -f /var/log/ipp-usb/<DEVICE>.log
```

#### **2.2 Display Full Log Files**

- **Show full contents of the main log file:**
```sh
cat /var/log/ipp-usb/main.log
```

- **Show logs for a specific device:**
```sh
cat /var/log/ipp-usb/<DEVICE>.log
```

#### **2.3 List Available Device Logs**

To see all available per-device log files, run:
```sh
ls /var/log/ipp-usb/
```

#### **3. Persisting Logs Across Container Restarts**

If you want logs to persist across container restarts, you should mount the log directory using a Docker volume or a host directory.

**Required Docker Flags for Log Persistence:**
- `-v <volume-name>:/var/log/ipp-usb` → Mounts a Docker volume for log persistence.
- **or**
- `-v <host-directory>:/var/log/ipp-usb` → Mounts a host directory to retain logs outside the container.

These options ensure that logs remain available even after the container stops or is recreated, allowing for easier troubleshooting and auditing.

## Installation from source

Expand Down
Loading