README ¶
Overlord ======== Overlord is a general purpose device monitoring and proxying framework. .. image:: https://goreportcard.com/badge/github.com/aitjcize/Overlord :target: https://goreportcard.com/report/github.com/aitjcize/Overlord Overlord provides a web interface which allows you to access device you have control of directly on the web. Features include: 1. shell access 2. file transfer 3. port forwarding 4. webcam streaming(directly from the web) 5. VPN(to be implemented) 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. **Opening terminals directly on the web-based dashboard** .. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/dashboard.gif **File upload via drag and drop** .. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/upload.gif **File download directly with HTTP download** .. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/download.gif Build ----- 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. Basic Deployment ---------------- 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). 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. 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>`_. 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``. 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>`_. Usage ----- 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. 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: 1. Connect to the overlord server .. code-block:: bash $ ovl connect SOME_SERVER_IP 9000 connect: Unauthorized: no authorization request Username: user Password: connection to SOME_SERVER_IP:9000 established. 2. List connected clients .. code-block:: bash $ ovl ls client1 client2 client3 3. Select default target to operate on .. code-block:: bash $ ovl select Select from the following clients: 1. client1 2. client2 3. client3 Selection: 1 4. Open a shell .. code-block:: bash $ ovl shell localhost ~ # _ 5. File transfer .. code-block:: bash % ovl push test_file /tmp test_file 9.9 KiB 38.1K/s 00:00 [#####################] 100% % ovl pull /tmp/test_file test_file2 test_file 9.9 KiB 1.1M/s 00:00 [#####################] 100% 6. Port forwarding: forward the port on client to localhost (assuming we have a web server running on client1's port 80) .. code-block:: bash % ovl forward 80 9000 % ovl forward --list Client Remote Local client1 80 9000 % wget 'http://localhost:9000' --2016-03-08 17:56:59-- http://localhost:9000/ Resolving localhost... ::1, 127.0.0.1 Connecting to localhost|::1|:9000... failed: Connection refused. Connecting to localhost|127.0.0.1|:9000... connected. HTTP request sent, awaiting response... 200 OK Length: 419 [text/html] Saving to: ‘index.html’ index.html 100%[===================>] 419 --.-KB/s in 0s 2016-03-08 17:57:00 (37.5 MB/s) - ‘index.html’ saved [419/419] Disclaimer ---------- 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.
Click to show internal directories.
Click to hide internal directories.