{"id":13508706,"url":"https://github.com/wallix/redemption","last_synced_at":"2025-05-16T08:05:07.737Z","repository":{"id":38431746,"uuid":"1619457","full_name":"wallix/redemption","owner":"wallix","description":"A GPL RDP proxy","archived":false,"fork":false,"pushed_at":"2025-04-01T13:40:49.000Z","size":286977,"stargazers_count":222,"open_issues_count":27,"forks_count":87,"subscribers_count":29,"default_branch":"future","last_synced_at":"2025-04-12T04:49:11.766Z","etag":null,"topics":["linux","proxy","rdp","redemption"],"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/wallix.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":"docs/ROADMAP.rst","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-04-15T15:09:21.000Z","updated_at":"2025-04-08T07:24:00.000Z","dependencies_parsed_at":"2023-10-20T10:53:15.735Z","dependency_job_id":"b3b4a66c-a75b-4373-ac40-b48ce8d2b6ee","html_url":"https://github.com/wallix/redemption","commit_stats":{"total_commits":17650,"total_committers":43,"mean_commits":410.4651162790698,"dds":0.7671954674220963,"last_synced_commit":"6de34f9e6047f5dd8d984804932c99022d8910b9"},"previous_names":[],"tags_count":769,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallix%2Fredemption","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallix%2Fredemption/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallix%2Fredemption/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wallix%2Fredemption/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wallix","download_url":"https://codeload.github.com/wallix/redemption/tar.gz/refs/heads/future","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"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":["linux","proxy","rdp","redemption"],"created_at":"2024-08-01T02:00:57.247Z","updated_at":"2025-05-16T08:05:02.728Z","avatar_url":"https://github.com/wallix.png","language":"C++","readme":"\u003c!-- Master branch: [![Build Status from master](https://travis-ci.org/wallix/redemption.svg?branch=master)](https://travis-ci.org/wallix/redemption) --\u003e\n\n\u003c!-- Future branch: [![Build Status from future](https://travis-ci.org/wallix/redemption.svg?branch=future)](https://travis-ci.org/wallix/redemption) --\u003e\n\n# About ReDemPtion\n\nRedemption is a versatile RDP proxy, meaning one will connect to remote desktops through Redemption.\nThis allows to centralize remote connection creating a single end point for several desktops.\nAbout the versatile part, Redemption is able to connect to VNC servers, permitting connection from Windows® to Linux, for instance.\nIt is only known to run on Linux (Ubuntu, Debian, Arch Linux) and no effort were made to port it to Win32, MacOS or FreeBSD.\n\nRedemption is also able to record sessions in .wrm/.mwrm files and then convert them to mp4 video.\n\nThe project also contains 2 RDP clients:\n\n- A desktop client in `projects/qtclient` (supports RDP and VNC)\n- A web client in `projects/jsclient` that uses a websocket (option that must be enabled in the proxy configuration).\n\n\n\u003c!-- generated with https://github.com/jonathanpoelen/gh-md-toc --\u003e\n\u003c!-- toc --\u003e\n1. [Compilation](#compilation)\n    1. [Dependencies](#dependencies)\n    2. [FFmpeg](#ffmpeg)\n        1. [Ubuntu / Debian](#ubuntu--debian)\n        2. [Other distros](#other-distros)\n    3. [Compile from source](#compile-from-source)\n    4. [Run tests](#run-tests)\n        1. [Verbose tests](#verbose-tests)\n        2. [Compilation error in test_snappy.cpp](#compilation-error-in-test_snappycpp)\n        3. [Runtime error in test_video_capture.cpp](#runtime-error-in-test_video_capturecpp)\n    5. [Modes and options](#modes-and-options)\n        1. [Setting build variables](#setting-build-variables)\n            1. [Local installation](#local-installation)\n            2. [ARM](#arm)\n    6. [Add .cpp file](#add-cpp-file)\n    7. [Update keylayout](#update-keylayout)\n2. [Run Redemption](#run-redemption)\n3. [Setting Redemption](#setting-redemption)\n    1. [Migrate the configuration to the next version](#migrate-the-configuration-to-the-next-version)\n4. [Session recording](#session-recording)\n    1. [Convert .mwrm/.wrm capture to video](#convert-mwrmwrm-capture-to-video)\n5. [Compile proxy_recorder](#compile-proxy_recorder)\n6. [Packaging](#packaging)\n7. [Test files](#test-files)\n\u003c!-- /toc --\u003e\n\n\n# Compilation\n\nFor automatic compilation, a Dockerfile is available.\nThis one is based on Ubuntu, but other linux systems are supported like Debian or Alpine.\n\nFor ARM, `-s TARGET=arm` must be added on the line containing `bjam`.\n\nThe following is for manual installation.\n\n\n## Dependencies\n\nTo compile Redemption you need the following packages:\n- libboost-tools-dev (contains bjam and b2: software build tool) (https://www.bfgroup.xyz/b2/)\n- libboost-test-dev (unit-test dependency)\n- zlib1g-dev\n- libssl-dev\n- libkrb5-dev\n- libsnappy-dev\n- libpng-dev\n- libbz2-dev\n- libhyperscan-dev\n- libffmpeg-dev (see below)\n- gettext (for `msgfmt` tool)\n- g++ \u003e= 13.0 or clang++ \u003e= 18.0 or other C++20 compiler\n\n```sh\napt install libboost-tools-dev libboost-test-dev libssl-dev libkrb5-dev libsnappy-dev libpng-dev libbz2-dev libhyperscan-dev\n```\n\n## FFmpeg\n\nIf your goal is to use the proxy without doing any video conversion (the recording is still available), you can disable FFmpeg by adding `NO_FFMPEG=1` to your environment variables before compiling.\n\nFor more information on available variables, see [Setting build variables](#setting-build-variables).\n\n### Ubuntu / Debian\n\nPackage:\n\n- libavcodec-dev\n- libavformat-dev\n- libavutil-dev\n- libswscale-dev\n- libx264-dev\n\n```sh\napt install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libx264-dev\n```\n\n\u003c!-- ok with 53 (?) and 54 version--\u003e\n\u003c!-- - libavcodec-ffmpeg56 --\u003e\n\u003c!-- - libavformat-ffmpeg56 --\u003e\n\u003c!-- - libavutil-ffmpeg54 --\u003e\n\u003c!-- - libswscale-ffmpeg3 --\u003e\n\n### Other distros\n\n- https://github.com/FFmpeg/FFmpeg/archive/n2.5.11.tar.gz (or later)\n\nAnd set the [build variables](#setting-build-variables) (optionally)\n- `FFMPEG_INC_PATH=/my/ffmpeg/include/path`\n- `FFMPEG_LIB_PATH=/my/ffmpeg/library/path` (/!\\\\ without `/` terminal)\n- `FFMPEG_LINK_MODE=shared` (static or shared, shared by default)\n\n\n## Compile from source\n\n([Instruction for Debian 9](https://github.com/wallix/redemption/issues/34#issuecomment-471322759)).\n\nWell, that's pretty easy once you installed the required dependencies.\n\nGo to the redemption folder then just run (as user):\n\n```sh\nbjam exe libs\n```\n\n(Always put a target name, otherwise the tests will also be compiled and executed).\n\nThen install (as administrator):\n\n```sh\nbjam install\n```\n\n`bjam install` depends on `exe libs`, if you have enough rights, it is not necessary to run the first command.\n\nBinaries are located by default in `/usr/local/bin`. For a user install, see [Local Installation](#local-installation).\n\nYou can choose your compiler and its version by adding `toolset=${compiler}` on the command line: `bjam toolset=gcc exe libs` / `bjam toolset=clang-16 exe libs` (see https://www.bfgroup.xyz/b2/manual/main/index.html#bbv2.overview.configuration and `tools/bjam/user-config.jam`).\n\nYou will find bjam auto-completion files for bash and zsh in the `tools/bjam` folder.\n\nNote: If you intend to make changes to the proxy, it is not necessary to reinstall it each time, the executable created in the `bin` folder can be run directly. It is also possible to install only resources via `bjam install-resources` without installing the executable and library.\n\n\n## Run tests\n\nTests are compiled and run with `bjam tests`. You can also compile everything (exe, lib, tests + runtime) with just `bjam` (without specifying a target).\n\nEach test file has its corresponding target and can be run independently:\n\n```sh\nbjam tests/utils/test_rect  # for tests/utils/test_rect.cpp\nbjam test_rect              # same\n```\n\nIn addition, each folder has an associated target name:\n\n```sh\nbjam tests/utils        # all tests in tests/utils/\nbjam tests/utils.norec  # all tests in tests/utils/, but not recursively (exclude sub-directories)\n```\n\nFor more user-friendly test output, you can look at what's in `tools/bjam`.\n\n\n### Verbose tests\n\nBy default, tests do not display log messages. These can be enabled by playing with the `REDEMPTION_LOG_PRINT` environment variable.\n\n```sh\nexport REDEMPTION_LOG_PRINT=1\nbjam tests\n```\n\n- `REDEMPTION_LOG_PRINT=1` enable all logs\n- `REDEMPTION_LOG_PRINT=e` for error and debug only\n- `REDEMPTION_LOG_PRINT=d` for debug only\n- `REDEMPTION_LOG_PRINT=w` for other than info\n\nIn debug mode and if the `BOOST_STACKTRACE` option is set, the `Error` constructor displays a call stack. This can be controlled with the environment variable `REDEMPTION_FILTER_ERROR` which contains a comma separated list of values to ignore.\n\n- `REDEMPTION_FILTER_ERROR=` no filter\n- `REDEMPTION_FILTER_ERROR='*'` filter all\n- `REDEMPTION_FILTER_ERROR=ERR_TRANSPORT_NO_MORE_DATA,ERR_SEC` filter specific errors (see `src/core/error.hpp`).\n\n\n### Compilation error in test_snappy.cpp\n\nUnder some versions of Ubuntu, Snappy dev files are broken and `SNAPPY_MAJOR`, `SNAPPY_MINOR` and `SNAPPY_PATCHLEVEL` macros are not defined.\nThe simplest way to fix that is editing `/usr/include/snappy-stubs-public.h` and define these above `SNAPPY_VERSION`.\n\nLike below (change values depending on your snappy package).\n\n```C\n// apt show libsnappy-dev | grep Version\n// Version: 1.1.7-1\n#define SNAPPY_MAJOR 1\n#define SNAPPY_MINOR 1\n#define SNAPPY_PATCHLEVEL 7\n```\n\n\n### Runtime error in test_video_capture.cpp\n\nThese errors should only occur after an FFmpeg update or regression.\n\nThe tests on the video generation check the size of the output files. This way of doing is not perfect and the result depends on the version of ffmpeg and the quality of the encoders. There is no other way than to change the range of possible values.\n\n\n## Modes and options\n\nBjam is configured to offer 3 compilation modes:\n\n- `release`: default\n- `debug`: Compile in debug mode\n- `san`: Compile in debug mode + sanitizers (asan, lsan, ubsan)\n\nThe mode is selected by adding `variant=${mode}` or simply `${mode}` to the bjam command line.\n\nThere are also several variables for setting compiler options:\n\n- `-s cxx-color`: default auto never always\n- `-s cxx-lto`: off on fat linker-plugin\n- `-s cxx-relro`: default off on full\n- `-s cxx-stack-protector`: off on strong all\n- ...\n\nComplete list with `bjam cxx_help`.\n\nFinally, `bjam` provides `cxxflags` and `linkflags` to add options to the compiler and linker. This is useful for example to remove warnings with the latest openssl versions.\n\n```sh\nbjam variant=debug -s cxx-lto=on cxxflags='-Wno-deprecated-declarations' targets...\n```\n\nBy default, `bjam` compiles everything into a folder named `bin`, you can change this with `--build-dir=new-path`.\n\n\n### Setting build variables\n\nList with `bjam env_help`.\n\nThese variables can be used as environment variables or passed on the bjam command line with `-s varname=value`.\n\nExample with ffmpeg:\n\n```sh\nbjam -s FFMPEG_INC_PATH=$HOME/ffmpeg/includes ....\n# or\nFFMPEG_INC_PATH=$HOME/ffmpeg/includes bjam ....\n# or\nexport FFMPEG_INC_PATH=$HOME/ffmpeg/includes bjam ....\nbjam ....\n```\n\n#### Local installation\n\nIf you have already compiled anything before this step, it is best to delete your `bin` folder (everything will be recompiled) or remove `app_path_exe.o` file inside.\n\nThe paths to the installed files can be listed with `bjam env_help`. The minimum requirement is the following (change the `install_path` variable to your liking).\n\n```sh\ninstall_path=\"$HOME/redemption\"\nexport PREFIX=\"$install_path\"/usr/local\nexport ETC_PREFIX=\"$install_path\"/etc\nexport VAR_PREFIX=\"$install_path\"/var\nexport SESSION_PREFIX=\"$install_path\"/var/lib\nexport PID_PATH=\"$install_path\"/var/run\nbjam ....\n```\n\n#### ARM\n\n```sh\nbjam -s TARGET=arm ....\n```\n\n`TARGET=arm` involves `NO_HYPERSCAN=1`.\n\n## Add .cpp file\n\nThe compiled files are referenced in `targets.jam`. This is a file that is generated via `./tools/bjam/gen_targets.py` and is updated with `bjam targets.jam` or `./tools/bjam/gen_targets.py \u003e targets.jam`.\n\nWhen you added a .cpp file or there is a link error, remember to run `bjam targets.jam`.\n\n## Update keylayout\n\nSee `tools/gen_keylayouts/`\n\n\n# Run Redemption\n\nFor a local test, the usual options are `-n` and `-f`.\nThe first option prevents Redemption from forking in the background and the second makes sure\nno other instance is running.\n\n```sh\nrdpproxy -nf\n```\n\u003c!-- $ `bin/${BJAM_TOOLSET_NAME}/${BJAM_MODE}/rdpproxy -nf` --\u003e\n\nAnd now what ? If everything went ok, you should be facing a waiting daemon !\nYou need two more things; first a client to connect to Redemption, second a\nserver with RDP running (a Windows server, Windows XP Pro, etc.).\n\nRedemption uses a hook file to get its target, username and password. This file\nis `tools/passthrough/passthrough.py` communicates with rdpproxy through a unix socket.\nThis is referenced as \"authentifier\" in proxy logs.\n\n```sh\n./tools/passthrough/passthrough.py\n```\n\nNow, at that point you'll just have two servers waiting for connections\nnot much fun. You still have to run some RDP client to connect to proxy. Choose\nwhichever you like xfreerdp, rdesktop, remmina, tsclient on Linux or of course\nmstsc.exe if you are on Windows. All are supposed to work. If some problem\noccurs just report it to us so that we can correct it.\n\nExamples with freerdp when the proxy runs on the same host as the client:\n\n```sh\nxfreerdp /v:127.0.0.1\n```\n\nA dialog box should open in which you can type a device ip, username and a password.\n\nThese 3 fields can be pre-filled by configuring the connection identifiers sent by your RDP client. With the default passthrough.py, the target address must be put with the login in the form `username@target_ip`:\n\n```sh\nxfreerdp /v:127.0.0.1 /u:username@10.10.43.11 /p:password\n```\n\nWith the default passthrough.py at least internal services should work. Try login `internal@bouncer2` or `internal@card`.\n\n```sh\nxfreerdp /v:127.0.0.1 /u:internal@bouncer2\n```\n\n`passthrough.py` is made to be edited and only provides the bare minimum. Here is a diagram that shows the basic interaction between these components:\n\n```mermaid\nflowchart LR\n    client[RDP Client] --\u003e rdpproxy[rdpproxy -nf]\n    rdpproxy --\u003e |user info|passthrough.py\n    passthrough.py --\u003e |\"remote target info:\u003cbr/\u003eusername, password\u003cbr/\u003e ...\"|rdpproxy\n    rdpproxy --\u003e server[RDP Server]\n```\n\n# Setting Redemption\n\nRedemption's configuration can be found in a `rdpproxy.ini` file that is not installed (you will have to create it yourself) or via the `--config-file=\u003cpath\u003e` option.\n\nThe default location of `rdpproxy.ini` can be found with the command `rdpproxy -c |\u0026 grep rdpproxy.ini` or `rdpinichecker`.\n\n`rdpproxy` also has a `--print-default-ini` which displays all the default options and values in comments. You can use `rdpinihecker -p` to get a condensed display.\n\nSome of these options can be modified by `passthrough.py` by filling in the dictionary sent to `send_data()`. See `tools/passthrough/README.md`.\n\n\n## Migrate the configuration to the next version\n\nBetween 2 versions, some options can be moved or deleted. `tools/conf_migration_tool/rdp_conf_migrate.py` allows to automatically migrate a file from an old version.\n\n\n# Session recording\n\nTo enable session recording, the line `kv['is_rec'] = '1'` in `passthrough.py` must be uncommented.\n\n\n## Convert .mwrm/.wrm capture to video\n\n`.mwrm` and `.wrm` are the native capture formats when recording is enabled.\nThe following line will transform a recording into an mp4 video:\n\n    redrec -u -i file.mwrm -o output_prefix\n\nNote: use `redrec -h` to see the list of options.\n\n\n# Compile proxy_recorder\n\nProxy recorder is a tools used to record dialog between a client and an RDP server without\nany modification of the data by redemption. This allows to record reference traffic for\nreplaying it later. It is useful for having available new parts or the RDP protocol in a\nreproducible way and replaying traffic when implementing the new orders. This tools is\nnot (yet) packaged with redemption and delivered as stand-alone.\n\nIt can be compiled using static c++ libraries (usefull to use the runtime on systems\nwhere reference compiler is older) using the command line below. Links with openssl\nand kerberos are still dynamic and using shared libraries.\n\n    bjam -a -d2 toolset=gcc-7 proxy_recorder linkflags=-static-libstdc++\n\nExemple call line for proxy_recorder:\n\n    proxy_recorder --target-host 10.10.47.252 -p 3389 -P 8000 --nla-username myusername --nla-password mypassword -t dump-%d.out\n\n\n# Packaging\n\nCreate Debian package with\n\n    ./packaging/package.sh\n\n\n# Test files\n\nSee [test_framework directory](tests/includes/test_only/test_framework).\n","funding_links":[],"categories":["C++","proxy"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwallix%2Fredemption","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwallix%2Fredemption","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwallix%2Fredemption/lists"}