github.com/aitjcize/Overlord@v0.0.0-20240314041920-104a804cf5e8/README.rst (about) 1 Overlord 2 ======== 3 Overlord is a general purpose device monitoring and proxying framework. 4 5 .. image:: https://goreportcard.com/badge/github.com/aitjcize/Overlord 6 :target: https://goreportcard.com/report/github.com/aitjcize/Overlord 7 8 Overlord provides a web interface which allows you to access device you have control of directly on the web. Features include: 9 10 1. shell access 11 2. file transfer 12 3. port forwarding 13 4. webcam streaming(directly from the web) 14 5. VPN(to be implemented) 15 16 and more. A CLI tool is also provided for accesing the connected clients. The Overlord server serve as a proxy, which means the devices are still accessible even if they are behind a NAT. 17 18 **Opening terminals directly on the web-based dashboard** 19 20 .. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/dashboard.gif 21 22 **File upload via drag and drop** 23 24 .. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/upload.gif 25 26 **File download directly with HTTP download** 27 28 .. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/download.gif 29 30 Build 31 ----- 32 Run ``make`` in the project root directory. ``make`` builds the overlord daemon and the go version of the ghost (overlord client). The resulting binary can be found in the ``bin`` directory. Note that You need to have the `Go <https://golang.org/>`_ compiler installed on your system. 33 34 Basic Deployment 35 ---------------- 36 1. On a server with public IP (to be used as a proxy), run ``overlordd -port 9000`` to start the server (if ``-port`` is not specified, default port is 80 or 443 depends on whether TLS is enabled or not). 37 2. On a client machine, run ``ghost SERVER_IP`` or ``ghost.py SERVER_IP``. ``ghost`` and ``ghost.py`` are functional equivalent except one is written in Python, and the other is written in Go. 38 3. Browse http://SERVER_IP:9000 and you will see the overlord web dashboard. The default user/password is ``overlord/cros``. To change the password, please follow the `Overlord advanced deployment guide <https://github.com/aitjcize/Overlord/blob/master/docs/deployment.rst#changing-default-password>`_. 39 40 For testing purpose, you can run both server and client on the same machine, then browse http://localhost:9000 instead. If you want to disable authentication of the web dashboard, you could add the ``-noauth`` option when starting ``overlordd``. 41 Overlord server supports a lot of features such as TLS encryption, client auto upgrade. For setting up these, please refer to the `Overlord advanced deployment guide <https://github.com/aitjcize/Overlord/blob/master/docs/deployment.rst>`_. 42 43 Usage 44 ----- 45 Overlord provides a web interface for interacting with the devices connected to it. The Overlord server provides a set of APIs that can be used for creating different apps(views) according to the need. The default dashboard provides an app-switcher on the top right corner. 46 47 Besides from the web interface, a command line interface is also provided. The ``ovl`` command (located at ``scripts/ovl.py``) not only provides the same functionality to the web interface but also provide command line only functions such as **port forwarding** and **VPN** (to be implemented). The basic usage is as follows: 48 49 1. Connect to the overlord server 50 51 .. code-block:: bash 52 53 $ ovl connect SOME_SERVER_IP 9000 54 connect: Unauthorized: no authorization request 55 Username: user 56 Password: 57 connection to SOME_SERVER_IP:9000 established. 58 59 2. List connected clients 60 61 .. code-block:: bash 62 63 $ ovl ls 64 client1 65 client2 66 client3 67 68 3. Select default target to operate on 69 70 .. code-block:: bash 71 72 $ ovl select 73 Select from the following clients: 74 1. client1 75 2. client2 76 3. client3 77 78 Selection: 1 79 80 4. Open a shell 81 82 .. code-block:: bash 83 84 $ ovl shell 85 localhost ~ # _ 86 87 5. File transfer 88 89 .. code-block:: bash 90 91 % ovl push test_file /tmp 92 test_file 9.9 KiB 38.1K/s 00:00 [#####################] 100% 93 % ovl pull /tmp/test_file test_file2 94 test_file 9.9 KiB 1.1M/s 00:00 [#####################] 100% 95 96 6. Port forwarding: forward the port on client to localhost (assuming we have a web server running on client1's port 80) 97 98 .. code-block:: bash 99 100 % ovl forward 80 9000 101 % ovl forward --list 102 Client Remote Local 103 client1 80 9000 104 % wget 'http://localhost:9000' 105 --2016-03-08 17:56:59-- http://localhost:9000/ 106 Resolving localhost... ::1, 127.0.0.1 107 Connecting to localhost|::1|:9000... failed: Connection refused. 108 Connecting to localhost|127.0.0.1|:9000... connected. 109 HTTP request sent, awaiting response... 200 OK 110 Length: 419 [text/html] 111 Saving to: ‘index.html’ 112 113 index.html 100%[===================>] 419 --.-KB/s in 0s 114 115 2016-03-08 17:57:00 (37.5 MB/s) - ‘index.html’ saved [419/419] 116 117 118 119 Disclaimer 120 ---------- 121 The Overlord project originates from the `Chromium OS factory repository <https://chromium.googlesource.com/chromiumos/platform/factory/>`_, which is used for monitoring and deploying test fixtures in a factory. The implementation of Overlord is general enough for non-factory use, thus, it's put into this GitHub mirror for greater visibility. All source code in this repository belongs to the `Chromium OS <https://www.chromium.org/chromium-os>`_ project and the source code is distributed under the same license.