github.com/aitjcize/Overlord@v0.0.0-20240314041920-104a804cf5e8/overlord/README.md (about) 1 # Overlord Deployment Guide 2 3 # Objective 4 5 The goal of this document is to provide deployment guidance to the 6 [Overlord](http://go/overlord-doc) factory monitor system. 7 8 # Basic Deployment 9 10 ## Get the source 11 12 The Overlord source code resides in the chromiumos factory repository. You can 13 clone the factory git repo without the entire chromiumos source tree: 14 15 ```bash 16 $ git clone https://chromium.googlesource.com/chromiumos/platform/factory 17 ``` 18 19 ## Build 20 21 Make sure you have the Go lang toolchain installed (`apt-get install 22 google-golang`). Building Overlord is as easy as typing `make` under the 23 `go/src/overlord` 24 25 ```bash 26 $ cd factory/go/src/overlord 27 28 $ make 29 ``` 30 31 ## Deploy 32 33 Assuming your server is located at `SHOPFLOOR_IP`, just scp the `go/bin` dir 34 onto the server 35 36 ```bash 37 $ scp -r factory/go/bin SHOPFLOOR_IP:~/overlord 38 ``` 39 40 In this particular case, we copy the bin folder onto the HOME/overlord on the 41 shopfloor server. 42 43 ## Start the Server 44 45 To start the server, simply run the overlordd binary 46 47 ```bash 48 shopfloor:~ $ cd overlord 49 50 shopfloor:~/overlord $ nohup ./overlordd & 51 ``` 52 53 One the server started, browse `http://SHOPFLOOR_IP:9000` to access the 54 overlord web frontend. 55 56 There are some options available for the overlordd command, use `overlord 57 -help` to see them. 58 59 By default, overlordd is started with HTTP basic auth enabled. The default 60 account / password is `overlord/cros`, **please follow the later section in 61 this document to change the password for production environment**. To disable 62 HTTP basic auth, simply add the `-noauth` option when launching overlordd. 63 **This is strongly discouraged in production environment**, as it expose your 64 server for anyone to access it. 65 66 ## Ghost Clients 67 68 The clients are called `ghost` in the Overlord framework. There are currently 69 two implementations, one implemented in python and the other implemented in go. 70 The python version can be found under the factory source repository: 71 `py/tools/ghost.py`; while the go version is under `go/src/overlord/ghost.go` 72 which is built along side with the `overlordd` binary under `go/bin`. 73 74 # Server Configuration 75 76 ## Changing LAN Discovery Broadcast Interface 77 78 Overlord server broadcasts LAN discovery messages into the subnet so clients 79 can identify the server IP. In a typical factory network, a server might have 80 at least two interface, one for LAN and another for external network. By 81 default, overlord broadcast the LAN discovery message to the default gateway's 82 subnet. To specify a different one, use the `-lan-disc-iface` option: 83 84 ```bash 85 shopfloor:~/overlord $ nohup ./overlordd -lan-disc-iface=eth1 & 86 ``` 87 88 ## Changing Default Password 89 90 The password to the Overlord server is stored in a apache style htpasswd file. 91 This means it supports multiple login credentials. To change it, first remove 92 the default password: 93 94 ```bash 95 shopfloor:~/overlord $ rm app/overlord.htpasswd 96 ``` 97 98 The use the htpasswd utility to create a new htpasswd file. The htpasswd 99 utility can be installed by `apt-get install apache2-utils`: 100 101 ```bash 102 shopfloor:~/overlord $ htpasswd -B -c app/overlord.htpasswd username11 103 104 New password: 105 Re-type new password: 106 Updating password for user username1 107 ``` 108 109 The `-c` option create the new file. To add more credentials to the file simply 110 remove the `-c` option: 111 112 ```bash 113 shopfloor:~/overlord $ htpasswd -B app/overlord.htpasswd username2 114 ``` 115 116 # Enable SSL Support 117 118 To ensure the privacy of the communication with the overlord server via the web 119 frontend. It`s encouraged to enable SSL on a production environment. 120 121 You can either use a CA-signed SSL certificate or a self-signed SSL 122 certificate. We usually use a self-signed certificate in the factory since we 123 can`t be 100% sure we are the only one that have access to the server. If the 124 partner have access to the server, they can steal your SSL certificate file! 125 126 To generate a self-signed SSL certificate, you need the openssl software suite 127 from you distribution: 128 129 ```bash 130 shopfloor:~/overlord $ openssl req -x509 -nodes -newkey rsa:2048 -keyout 131 key.pem -out cert.pem -days 365 132 ``` 133 134 **Note that you need to input the correct `common name` when generating the 135 certificate, `common name` is typically the FQDN or IP of the server.** 136 137 This will generate two files: `cert.pem` and `key.pem`. Assign it to the `-tls` 138 option when starting overlordd, and you are all set. 139 140 ```bash 141 shopfloor:~/overlord $ nohup ./overlordd -tls=cert.pem,key.pem & 142 ``` 143 144 Now you can browse `https://shopfloor_ip:9000` to access the web frontend. 145 Note that you need to use `https` instead of `http`. 146 147 **Connecting to a TLS enabled Server** 148 149 ghost automatically detects if Overlord server has TLS enabled and verify it 150 using system installed ca-certificates bundle. 151 152 To connect to a TLS enabled Overlord server, a ghost client must specify the 153 TLS certificate to be used for verification: 154 155 ```bash 156 $ ghost --tls-cert-file cert.pem SERVER_IP 157 ``` 158 159 Optionally, one could enable TLS but skip certificate verification: 160 161 ```bash 162 $ ghost --tls-no-verify SERVER_IP 163 ``` 164 165 ## Caveats 166 167 The SSL certification generated above is a self-signed SSL certificate. The 168 first time you visit the web frontend, you will see a warning. 169 170 This is the result of self-signed SSL certificate, no need to panic. Click on 171 the left top corner of the browser to see the certificate information. 172 173 **Make sure the fingerprint is correct** then hit the `Advanced` button then 174 `Proceed`. 175 176 # Auto Upgrade Setup 177 178 Overlord supports an AU(Auto Upgrade) protocol for updating ghost clients. 179 Ghost clients automatically check for update on registration. Admins can also 180 force an upgrade if there are updates available. 181 182 ## Prepare Upgrade Files 183 184 Fetch the latest ghost.py or ghost binary from factory repo. For the ghost 185 binary, rename it into ghost.ARCH, where `ARCH` is go runtime.GOARCH variable 186 on that platform. For a x86\_64 platform, the runtime.GOARCH equals `amd64`. In 187 such case, rename the binary to `ghost.amd64`. 188 189 ## Copy the Upgrade File Onto the Server 190 191 ### Create the required directory structure 192 193 On the Shopfloor server: 194 195 ```bash 196 shopfloor:~/overlord $ mkdir app/upgrade 197 ``` 198 199 ### Copy the Upgrade file 200 201 ```bash 202 $ scp ghost.py SHOPFLOOR_IP:~/overlord/app/upgrade 203 204 $ scp ghost.amd64 SHOPFLOOR_IP:~/overlord/app/upgrade 205 ``` 206 207 ### Generate Checksum 208 209 ```bash 210 shopfloor:~/overlord $ cd app/upgrade 211 212 shopfloor:~/overlord/app/upgrade $ for i in `ls ghost.* | grep -v sha1`; do \ 213 sha1sum $i | awk '{ print $1 }' > $i.sha1 done 214 ``` 215 216 ### Force Upgrade 217 218 After the above step, the upgrade files are ready. Now if a new client connects 219 or client reconnects to the overlord server, it automatically checks for 220 upgrade and apply it. To force an upgrade for already connected clients, simply 221 send a GET request to the server: 222 223 ```bash 224 $ curl -k -u username1:password1 'https://127.0.0.1:9000/api/agents/upgrade' 225 ``` 226 227 (Note: use `http` if you don't have SSL enabled)