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.