os-brick

7.0.0 verified Mon Apr 27 auth: no python

OpenStack Cinder brick library for managing local volume attaches. Used by Cinder and Nova to connect and disconnect volumes (iSCSI, Fibre Channel, NFS, etc.). Current version 7.0.0, supports Python >=3.10. Releases follow OpenStack cycle, with stable releases every 6 months.

pip install os-brick

Common errors

error ImportError: No module named os_brick ↓

cause os-brick is not installed or virtual environment not activated.

fix

pip install os-brick

error PermissionError: [Errno 13] Permission denied: '/sys/class/scsi_host' ↓

cause Script not run as root; os-brick needs root to discover SCSI hosts.

fix

Run the script with sudo: sudo python your_script.py

error TypeError: get_connector_properties() missing 1 required positional argument: 'my_ip' ↓

cause In os-brick >=7.0.0, 'my_ip' is a required argument.

fix

Provide the host IP: get_connector_properties(root_helper='sudo', my_ip='192.168.1.10')

error os_brick.exception.ProtocolNotSupported: Protocol iscsi is not supported ↓

cause iSCSI tools (iscsiadm, etc.) not installed on the system.

fix

Install open-iscsi or appropriate package: sudo apt-get install open-iscsi (Debian/Ubuntu)

error AttributeError: module 'os_brick' has no attribute 'initiator' ↓

cause os-brick library is very old (<2.0) or installed incorrectly (e.g., from source without setup).

fix

Upgrade to latest: pip install --upgrade os-brick

Warnings

breaking os-brick 7.0.0 drops support for Python <3.10. Ensure your environment uses Python 3.10+. ↓

fix Upgrade to Python 3.10 or later before installing os-brick>=7.0.0.

breaking In version 7.0.0, the 'root_helper' parameter is required in many connector methods. Previously it defaulted to 'sudo'. Now it must be explicitly provided or set via config. ↓

fix Pass root_helper='sudo' (or appropriate helper) to connector factory or get_connector_properties.

gotcha os-brick requires root privileges for most operations (e.g., scanning iSCSI, partitioning). Running without root will result in PermissionError. ↓

fix Run your Python script with sudo or ensure the user has passwordless sudo for the root_helper command.

gotcha The initiator connector classes are not thread-safe. Do not share connector instances across threads. ↓

fix Create a new connector per thread or use locking (e.g., oslo_concurrency.lockutils).

deprecated Use of 'os_brick.remotefs' module is deprecated in favor of 'os_brick.initiator.connectors.remotefs'. ↓

fix Import from os_brick.initiator.connectors.remotefs instead of os_brick.remotefs.

Install

pip install os-brick[fibre_channel]

Imports

get_connector_properties
wrong
```
from cinder.volume import driver
```
correct
```
from os_brick.initiator import connector
```
os-brick is a standalone library; never import via cinder paths

InitiatorConnector

wrong

from os_brick.connector import InitiatorConnector

correct

from os_brick.initiator import connector

InitiatorConnector is under os_brick.initiator.connector

LinuxConnectorMixin

wrong

from os_brick.base import LinuxConnectorMixin

correct

from os_brick.initiator.connectors import base

base class is in os_brick.initiator.connectors.base

Quickstart

Retrieve host connector properties (initiator name, WWNs, etc.) for volume attachment.

import os
from os_brick.initiator import connector

# Get connector properties (must be root or have appropriate privileges)
props = connector.get_connector_properties(
    root_helper='sudo',
    my_ip='192.168.1.10',
    multipath=True,
    enforce_multipath=False
)
print(props)

# Example: create an iSCSI connector (requires root)
# conn = connector.InitiatorConnector.factory('iscsi', root_helper='sudo')
# conn.connect_volume(connection_properties)  # volume must be present