{"id":21666,"library":"os-brick","title":"os-brick","description":"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.","status":"active","version":"7.0.0","language":"python","source_language":"en","source_url":"https://opendev.org/openstack/os-brick","tags":["openstack","cinder","volume","storage","connector","iscsi","fibre-channel"],"install":[{"cmd":"pip install os-brick","lang":"bash","label":"Install from PyPI"},{"cmd":"pip install os-brick[fibre_channel]","lang":"bash","label":"Install with FC support (optional)"}],"dependencies":[{"reason":"lockutils for file locking","package":"oslo.concurrency","optional":false},{"reason":"privilege separation for root operations","package":"oslo.privsep","optional":false},{"reason":"udev device detection","package":"pyudev","optional":false},{"reason":"libvirt integration for qemu connections","package":"libvirt-python","optional":true}],"imports":[{"note":"os-brick is a standalone library; never import via cinder paths","wrong":"from cinder.volume import driver","symbol":"get_connector_properties","correct":"from os_brick.initiator import connector"},{"note":"InitiatorConnector is under os_brick.initiator.connector","wrong":"from os_brick.connector import InitiatorConnector","symbol":"InitiatorConnector","correct":"from os_brick.initiator import connector"},{"note":"base class is in os_brick.initiator.connectors.base","wrong":"from os_brick.base import LinuxConnectorMixin","symbol":"LinuxConnectorMixin","correct":"from os_brick.initiator.connectors import base"}],"quickstart":{"code":"import os\nfrom os_brick.initiator import connector\n\n# Get connector properties (must be root or have appropriate privileges)\nprops = connector.get_connector_properties(\n    root_helper='sudo',\n    my_ip='192.168.1.10',\n    multipath=True,\n    enforce_multipath=False\n)\nprint(props)\n\n# Example: create an iSCSI connector (requires root)\n# conn = connector.InitiatorConnector.factory('iscsi', root_helper='sudo')\n# conn.connect_volume(connection_properties)  # volume must be present\n","lang":"python","description":"Retrieve host connector properties (initiator name, WWNs, etc.) for volume attachment."},"warnings":[{"fix":"Upgrade to Python 3.10 or later before installing os-brick>=7.0.0.","message":"os-brick 7.0.0 drops support for Python <3.10. Ensure your environment uses Python 3.10+.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Pass root_helper='sudo' (or appropriate helper) to connector factory or get_connector_properties.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Run your Python script with sudo or ensure the user has passwordless sudo for the root_helper command.","message":"os-brick requires root privileges for most operations (e.g., scanning iSCSI, partitioning). Running without root will result in PermissionError.","severity":"gotcha","affected_versions":"all"},{"fix":"Create a new connector per thread or use locking (e.g., oslo_concurrency.lockutils).","message":"The initiator connector classes are not thread-safe. Do not share connector instances across threads.","severity":"gotcha","affected_versions":"all"},{"fix":"Import from os_brick.initiator.connectors.remotefs instead of os_brick.remotefs.","message":"Use of 'os_brick.remotefs' module is deprecated in favor of 'os_brick.initiator.connectors.remotefs'.","severity":"deprecated","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"pip install os-brick","cause":"os-brick is not installed or virtual environment not activated.","error":"ImportError: No module named os_brick"},{"fix":"Run the script with sudo: sudo python your_script.py","cause":"Script not run as root; os-brick needs root to discover SCSI hosts.","error":"PermissionError: [Errno 13] Permission denied: '/sys/class/scsi_host'"},{"fix":"Provide the host IP: get_connector_properties(root_helper='sudo', my_ip='192.168.1.10')","cause":"In os-brick >=7.0.0, 'my_ip' is a required argument.","error":"TypeError: get_connector_properties() missing 1 required positional argument: 'my_ip'"},{"fix":"Install open-iscsi or appropriate package: sudo apt-get install open-iscsi (Debian/Ubuntu)","cause":"iSCSI tools (iscsiadm, etc.) not installed on the system.","error":"os_brick.exception.ProtocolNotSupported: Protocol iscsi is not supported"},{"fix":"Upgrade to latest: pip install --upgrade os-brick","cause":"os-brick library is very old (<2.0) or installed incorrectly (e.g., from source without setup).","error":"AttributeError: module 'os_brick' has no attribute 'initiator'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}