{"id":13743305,"url":"https://github.com/ublk-org/ublksrv","last_synced_at":"2026-04-09T00:10:01.628Z","repository":{"id":40514617,"uuid":"474672135","full_name":"ublk-org/ublksrv","owner":"ublk-org","description":"ublk: userspace block device driver","archived":false,"fork":false,"pushed_at":"2026-03-18T02:23:07.000Z","size":1525,"stargazers_count":195,"open_issues_count":22,"forks_count":79,"subscribers_count":11,"default_branch":"master","last_synced_at":"2026-03-18T05:57:43.291Z","etag":null,"topics":["block","coroutine","iouring","linux","nbd","storage","ublk","userspace"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ublk-org.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-03-27T15:05:18.000Z","updated_at":"2026-03-18T02:12:44.000Z","dependencies_parsed_at":"2023-02-19T08:30:32.909Z","dependency_job_id":"523363c4-8d2d-4fcc-bede-fb5cba65908c","html_url":"https://github.com/ublk-org/ublksrv","commit_stats":null,"previous_names":["ublk-org/ublksrv","ming1/ubdsrv"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/ublk-org/ublksrv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublk-org%2Fublksrv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublk-org%2Fublksrv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublk-org%2Fublksrv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublk-org%2Fublksrv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ublk-org","download_url":"https://codeload.github.com/ublk-org/ublksrv/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ublk-org%2Fublksrv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31579095,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["block","coroutine","iouring","linux","nbd","storage","ublk","userspace"],"created_at":"2024-08-03T05:00:44.265Z","updated_at":"2026-04-09T00:10:01.622Z","avatar_url":"https://github.com/ublk-org.png","language":"C++","funding_links":[],"categories":["Libraries"],"sub_categories":["C++"],"readme":"\n============================\nUserspace block driver(ublk)\n============================\n\nIntroduction\n============\n\nThis is the userspace daemon part(ublksrv) of the ublk framework, the other\npart is ``ublk driver`` [#userspace]_  which supports multiple queue.\n\nThe two parts communicate by io_uring's IORING_OP_URING_CMD with one\nper-queue shared cmd buffer for storing io command, and the buffer is\nread only for ublksrv, each io command can be indexed by io request tag\ndirectly, and the command is written by ublk driver, and read by ublksrv\nafter getting notification from ublk driver.\n\nFor example, when one READ io request is submitted to ublk block driver, ublk\ndriver stores the io command into cmd buffer first, then completes one\nIORING_OP_URING_CMD for notifying ublksrv, and the URING_CMD is issued to\nublk driver beforehand by ublksrv for getting notification of any new io\nrequest, and each URING_CMD is associated with one io request by tag,\nso depth for URING_CMD is same with queue depth of ublk block device.\n\nAfter ublksrv gets the io command, it translates and handles the ublk io\nrequest, such as, for the ublk-loop target, ublksrv translates the request\ninto same request on another file or disk, like the kernel loop block\ndriver. In ublksrv's implementation, the io is still handled by io_uring,\nand share same ring with IORING_OP_URING_CMD command. When the target io\nrequest is done, the same IORING_OP_URING_CMD is issued to ublk driver for\nboth committing io request result and getting future notification of new\nio request.\n\nublk supports io-uring based buffer register zero copy. For using it, pass\n`UBLK_F_SUPPORT_ZERO_COPY` or `UBLK_F_AUTO_BUF_REG` to ublk driver, please\nrefer to `Zero copy` and `Auto Buffer Registration` section of ublk kernel\ndocument. [#zero_copy]_\n\nMore ublk targets will be added with this framework in future even though only\nublk-loop and ublk-null are implemented now.\n\nlibublksrv is also generated, and it helps to integrate ublk into existed\nproject. One example of demo_null is provided for how to make a ublk\ndevice over libublksrv.\n\nBuild Dependencies\n==================\n\n**Fedora/RHEL/CentOS:**\n\n.. code-block:: console\n\n  dnf install git libtool automake autoconf g++ pkgconf-pkg-config liburing-devel\n\n**Ubuntu/Debian:**\n\n.. code-block:: console\n\n  apt install git libtool automake autoconf g++ pkg-config liburing-dev\n\nQuick start\n===========\n\nhow to build ublksrv:\n--------------------\n\n.. code-block:: console\n\n  autoreconf -i\n  ./configure   #pkg-config and libtool is usually needed\n  make\n\nnote: './configure' requires liburing 2.2 package installed, if liburing 2.2\nisn't available in your distribution, please configure via the following\ncommand, or refer to ``build_with_liburing_src`` [#build_with_liburing_src]_\n\n.. code-block:: console\n\n   PKG_CONFIG_PATH=${LIBURING_DIR} \\\n   ./configure \\\n    CFLAGS=\"-I${LIBURING_DIR}/src/include\" \\\n    CXXFLAGS=\"-I${LIBURING_DIR}/src/include\" \\\n    LDFLAGS=\"-L${LIBURING_DIR}/src\"\n\nand LIBURING_DIR points to directory of liburing source code, and liburing\nneeds to be built before running above commands. Also IORING_SETUP_SQE128\nhas to be supported in the liburing source.\n\nc++20 is required for building ublk utility, but libublksrv and demo_null.c \u0026\ndemo_event.c can be built independently:\n\n- build libublksrv ::\n\n    make -C lib/\n\n- build demo_null \u0026\u0026 demo_event ::\n\n    make -C lib/\n    make demo_null demo_event\n\nhelp\n----\n\n- ublk help\n\nadd one ublk-null disk\n----------------------\n\n- ublk add -t null\n\n\nadd one ublk-loop disk\n----------------------\n\n- ublk add -t loop -f /dev/vdb\n\nor\n\n- ublk add -t loop -f 1.img\n\nremove one ublk disk\n--------------------\n\n- ublk del -n 0\t\t#remove /dev/ublkb0\n\n- ublk del -a\t\t#remove all ublk devices\n\nlist ublk devices\n---------------------\n\n- ublk list\n\n- ublk list -v\t#with all device info dumped\n\n\nunprivileged mode\n==================\n\nTypical use case is container [#stefan_container]_ in which user\ncan manage its own devices not exposed to other containers.\n\nAt default, controlling ublk device needs privileged user, since\n/dev/ublk-control is permitted for administrator only, and this\nis called privileged mode.\n\nFor unprivilege mode, /dev/ublk-control needs to be allowed for\nall users, so the following udev rule need to be added:\n\nKERNEL==\"ublk-control\", MODE=\"0666\", OPTIONS+=\"static_node=ublk-control\"\n\nAlso when new ublk device is added, we need ublk to change device\nownership to the device's real owner, so the following rules are\nneeded: ::\n\n    KERNEL==\"ublkc*\",RUN+=\"ublk_chown.sh %k\"\n    KERNEL==\"ublkb*\",RUN+=\"ublk_chown.sh %k\"\n\n``ublk_chown.sh`` can be found under ``utils/`` too.\n\n``utils/ublk_dev.rules`` includes the above rules.\n\nWith the above two administrator changes, unprivileged user can\ncreate/delete/list/use ublk device, also anyone which isn't permitted\ncan't access and control this ublk devices(ublkc*/ublkb*)\n\nUnprivileged user can pass '--unprevileged' to 'ublk add' for creating\nunprivileged ublk device, then the created ublk device is only available\nfor the owner and administrator.\n\nuse unprivileged ublk in docker\n-------------------------------\n\n- install the following udev rules in host machine: ::\n\n    ACTION==\"add\",KERNEL==\"ublk[bc]*\",RUN+=\"/usr/local/sbin/ublk_chown_docker.sh %k 'add' '%M' '%m'\"\n    ACTION==\"remove\",KERNEL==\"ublk[bc]*\",RUN+=\"/usr/local/sbin/ublk_chown_docker.sh %k 'remove' '%M' '%m'\"\n\n``ublk_chown_docker.sh`` can be found under ``utils/``.\n\n- run one container and install ublk \u0026 its dependency packages\n\n.. code-block:: console\n\n  docker run \\\n    --name fedora \\\n    --hostname=ublk-docker.example.com \\\n    --device=/dev/ublk-control \\\n    --device-cgroup-rule='a *:* rmw' \\\n    --tmpfs /tmp \\\n    --tmpfs /run \\\n    --volume /sys/fs/cgroup:/sys/fs/cgroup:ro \\\n    -ti \\\n    fedora:38\n\n.. code-block:: console\n\n  #run the following commands inside the above container\n  dnf install -y git libtool automake autoconf g++ pkgconf-pkg-config liburing-devel\n  git clone https://github.com/ming1/ubdsrv.git\n  cd ubdsrv\n  autoreconf -i\u0026\u0026 ./configure\u0026\u0026 make -j 4\u0026\u0026 make install\n\n- add/delete ublk device inside container by unprivileged user\n\n.. code-block:: console\n\n  docker exec -u 1001:1001 -ti fedora /bin/bash\n\n.. code-block:: console\n\n  #run the following commands inside the above container\n  bash-5.2$ ublk add -t null --unprivileged\n    dev id 0: nr_hw_queues 1 queue_depth 128 block size 512 dev_capacity 524288000\n    \tmax rq size 524288 daemon pid 178 flags 0x62 state LIVE\n    \tublkc: 237:0 ublkb: 259:1 owner: 1001:1001\n    \tqueue 0: tid 179 affinity(0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 )\n    \ttarget {\"dev_size\":268435456000,\"name\":\"null\",\"type\":0}\n\n  bash-5.2$ ls -l /dev/ublk*\n    crw-rw-rw-. 1 root root  10, 123 May  1 04:35 /dev/ublk-control\n    brwx------. 1 1001 1001 259,   1 May  1 04:36 /dev/ublkb0\n    crwx------. 1 1001 1001 237,   0 May  1 04:36 /dev/ublkc0\n\n  bash-5.2$ ublk del -n 0\n  bash-5.2$ ls -l /dev/ublk*\n    crw-rw-rw-. 1 root root 10, 123 May  1 04:35 /dev/ublk-control\n\n- example of ublk in docker: ``tests/debug/ublk_docker``\n\ntest\n====\n\nrun all built tests\n-------------------\n\nmake test T=all\n\n\nrun test group\n--------------\n\nmake test T=null\n\nmake test T=loop\n\nmake test T=generic\n\n\nrun single test\n---------------\n\nmake test T=generic/001\n\nmake test T=null/001\n\nmake test T=loop/001\n...\n\nrun specified tests or test groups\n----------------------------------\n\nmake test T=generic:loop/001:null\n\n\nDebug\n=====\n\nublksrv is running as one daemon process, so most of debug messages won't be\nshown in terminal. If any issue is observed, please collect log via command\nof \"journalctl | grep ublksrvd\"\n\n``./configure --enable-debug`` can build a debug version of ublk which\ndumps lots of runtime debug messages, and can't be used in production\nenvironment, should be for debug purpose only. For debug version of\nublksrv, 'ublk add --debug_mask=0x{MASK}' can control which kind of\ndebug log dumped, see ``UBLK_DBG_*`` defined in include/ublksrv_utils.h\nfor each kind of debug log.\n\nlibublksrv API doc\n==================\n\nAPI is documented in include/ublksrv.h, and doxygen doc can be generated\nby running 'make doxygen_doc', the generated html docs are in doc/html.\n\nContributing\n============\n\nAny kind of contribution is welcome!\n\nDevelopment is done over github.\n\nMaillist\n========\n\nA ublk mailing list is available at http://groups.google.com/group/ublk.\n\nLicense\n=======\n\nnlohmann(include/nlohmann/json.hpp) is from [#nlohmann]_, which is covered\nby MIT license.\n\nThe library functions (all code in lib/ directory and include/ublksrv.h)\nare covered by dual licensed LGPL and MIT, see COPYING.LGPL and LICENSE.\n\nAll other source code are covered by dual licensed GPL and MIT, see\nCOPYING and LICENSE.\n\nReferences\n==========\n\n.. [#ublk_driver] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/block/ublk_drv.c?h=v6.0\n.. [#zero_copy] https://www.kernel.org/doc/Documentation/block/ublk.rst\n.. [#nlohmann] https://github.com/nlohmann/json\n.. [#build_with_liburing_src] https://github.com/ming1/ubdsrv/blob/master/build_with_liburing_src\n.. [#stefan_container] https://lore.kernel.org/linux-block/YoOr6jBfgVm8GvWg@stefanha-x1.localdomain/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fublk-org%2Fublksrv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fublk-org%2Fublksrv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fublk-org%2Fublksrv/lists"}