{"id":18794835,"url":"https://github.com/acerv/ltx","last_synced_at":"2025-12-29T22:30:14.534Z","repository":{"id":172672097,"uuid":"649594305","full_name":"acerv/ltx","owner":"acerv","description":"Linux Test eXecutor","archived":false,"fork":false,"pushed_at":"2024-01-26T15:35:55.000Z","size":88,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-29T16:36:56.677Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acerv.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2023-06-05T08:11:55.000Z","updated_at":"2024-01-26T12:32:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"0f7ed266-1da9-4e1b-9087-2e0ef0339deb","html_url":"https://github.com/acerv/ltx","commit_stats":null,"previous_names":["acerv/ltx"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerv%2Fltx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerv%2Fltx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerv%2Fltx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acerv%2Fltx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acerv","download_url":"https://codeload.github.com/acerv/ltx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239719154,"owners_count":19685898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-11-07T21:31:15.278Z","updated_at":"2025-12-29T22:30:14.469Z","avatar_url":"https://github.com/acerv.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linux Test (Project) Executor\n\nThe `ltx` program runs on the system under test (SUT). It's primary\npurpose is to run test executables in parallel and serialise the\nresults. It is a dumb program that executes simple commands sent to it\nby a test scheduler. The commands are encoded as [MessagePack] arrays as\nare the results.\n\nThe first element of the array is the message type, represented as an\ninteger. The rest of the array contents (if any) depend on the message\ntype.\n\nIn classic UNIX fashion, stdin and stdout are used to receive and send\ncommands. This makes LTX transport agnostic, a program such as\n`socat`, `ssh` or just `sh` can be used to redirect the standard I/O\nof LTX.\n\n## Dependencies\n\nLTX itself just needs Clang or GCC. The tests require Python 3.7+ with\n`pytest` and `msgpack`. To build LTX, we can use `make` command:\n\n    # regular build\n    make\n    # debug build\n    make debug\n\n## Build\n\nLTX can also be built as library in order to link its API inside a project and\nto run a custom initialization process for specific systems, such as `initrd`.\n\n    # libltx build\n    make shared\n    # shared debug build\n    make shared-debug\n\nFor testing:\n\n    # tests build\n    make test\n\n    # execute tests\n    ./tests/test_utils\n    ./tests/test_message\n    ./tests/test_unpack\n\n    # install python 3.7+ dependences\n    virtualenv .venv\n    source .venv/bin/activate\n    pip install pytest msgpack\n\n    # execute LTX communication tests\n    pytest -v tests/test_ltx.py\n\n## Run inside container\n\nWe provide a `Dockerfile` that can be used to run LTX inside a container.\nThe container can be built and run as following:\n\n    # build docker container\n    docker build -t ltx .\n\n    # create communication pipes\n    mkfifo transport.in\n    mkfifo transport.out\n\n    # run ltx inside container\n    docker run --interactive ltx \u003c transport.in \u003e transport.out\n\nNow it's possible to communicate with `ltx` via `transport.in` and \n`transport.out` pipes using `msgpack`.\n\n## Messages\n\nLTX is not intended to have a generic [MessagePack] parser. There are\nseveral ways in which a message can be encoded. However you can assume\nLTX only accepts the shortest possible encoding.\n\n### Version\n\nCheck for LTX version.\n\nRequest:\n\n| fixarray | uint   |\n|:---------|:-------|\n| `0x91`   | `0x00` |\n\nReply:\n\n| fixarray | uint   | string   |\n|:---------|:-------|:---------|\n| `0x92`   | `0x00` | version  |\n\n### Ping\n\nSend ping to the service. Pong reply will have a nano seconds time stamp taken\nwith `CLOCK_MONOTONIC`.\n\nRequest:\n\n| fixarray | uint   |\n|:---------|:-------|\n| `0x91`   | `0x01` |\n\nReply:\n\n| fixarray | uint   | uint    |\n|:---------|:-------|:--------|\n| `0x92`   | `0x02` | time_ns |\n\n### Get file\n\nRead file from the system. LTX will start to send file content via `Data` reply.\nEach `Data` reply contains maximum `1024` bytes and when all `Data` replies are\nsent, LTX will echo back the request. **NOTE**: LTX won't process anything else\nuntil `Get file` request is completed.\n\nRequest:\n\n| fixarray | uint   | string    |\n|:---------|:-------|:----------|\n| `0x92`   | `0x03` | file path |\n\nData:\n\n| fixarray | uint   | bytes        |\n|:---------|:-------|:-------------|\n| `0x92`   | `0xa0` | file content |\n\n### Set file\n\nWrite file on target. Reply message will be identical to the request message,\nexcept for the file content data, which is removed to speed up communication.\n**NOTE**: LTX won't process anything else until `Set file` request is completed.\n\nRequest:\n\n| fixarray | uint   | string    | bytes        |\n|:---------|:-------|:----------|:-------------|\n| `0x93`   | `0x04` | file path | file content |\n\nReply:\n\n| fixarray | uint   | string    |\n|:---------|:-------|:----------|\n| `0x92`   | `0x04` | file path |\n\n### Env\n\nSet environment variable to a specific `slot_id` or all slots. Once message is\nprocessed, request is echoed back. To set `Env` for all slots use `slot_id`\nnumber `128`.\n\nRequest:\n\n| fixarray | uint   | uint    | string | string |\n|:---------|:-------|:------- |:-------|:-------|\n| `0x94`   | `0x05` | slot_id | key    | value  |\n\n### Cwd\n\nSet current working directory for a specific `slot_id` or all slots. Once\nmessage is processed, request is echoed back. To set `Cwd` for all slots use\n`slot_id` number `128`.\n\nRequest:\n\n| fixarray | uint   | uint    | string |\n|:---------|:-------|:------- |:-------|\n| `0x93`   | `0x06` | slot_id | path   |\n\n### Exec\n\nExecute a command inside a specific `slot_id`. Once message is processed,\nrequest is echoed back, then `Log` messages are sent when reading command\nstdout and at the end a `Result` message is sent. The `Result` execution time\nwill have a nano seconds time stamp taken with `CLOCK_MONOTONIC`.\n\nRequest:\n\n| fixarray | uint   | uint    | string    |\n|:---------|:-------|:------- |:----------|\n| `0x93`   | `0x07` | slot_id | command   |\n\nLog:\n\n| fixarray | uint   | uint    | string    |\n|:---------|:-------|:------- |:----------|\n| `0x93`   | `0x09` | slot_id | stdout    |\n\nResult:\n\n| fixarray | uint   | uint    | uint    | uint    | uint      |\n|:---------|:-------|:------- |:--------|:--------|:----------|\n| `0x95`   | `0x08` | slot_id | exec_ns | si_code | si_status |\n\n### Kill\n\nKill execution on a particular `slot_id`. Once message is processed, request is\nechoed back and related `Exec` request is processed after a `SIGKILL`. So expect\nto receive the last `Log` messages as well as a `Result` message.\n\nRequest:\n\n| fixarray | uint   | uint    |\n|:---------|:-------|:------- |\n| `0x92`   | `0xa1` | slot_id |\n\n### Error\n\nAll the times and error occurs inside LTX, this message is sent. This message\ncan literally arrive in any moment, so be sure to process error type before any\nmessage is received from LTX.\n\nReply:\n\n| fixarray | uint   | string       |\n|:---------|:-------|:-------------|\n| `0x92`   | `0xff` | error string |\n\n\n[MessagePack]: https://github.com/msgpack/msgpack/blob/master/spec.md\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facerv%2Fltx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facerv%2Fltx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facerv%2Fltx/lists"}