diff --git a/README.md b/README.md index 468136f..7df3871 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,131 @@ ansible-lssd ============ Large scale server deploys using BitTorrent and the BitTornado library by [Murder](https://github.com/lg/murder) + +DESCRIPTION +----------- +ansible-lssd is a method of using Bittorrent (Powered by [Murder](https://github.com/lg/murder)) to distribute files to a large amount +of servers within a production environment. + + +QUICK START +----------- + +For the impatient, `sudo pip install ansible` and add these lines to your group_vars/all: + +```bash: +# install pip (Python package manager) and ansible +$ sudo easy_install pip +$ sudo pip install ansible +``` + +```YAML:group_vars/all +# deploy tag +tag: Deploy1 + +# path +seeder_files_path: ~/builds +destination_path: /opt/hoge +``` + + +HOW IT WORKS +------------ + +Same as the "[HOW IT WORKS](https://github.com/lg/murder/blob/master/README.md#how-it-works)" of Murder. + + +CONFIGURATION AND USAGE +----------------------- + +You define `tracker`, `seeder` and `peer` server to inventory (./production) file. + +All involved servers must have python and pizg installed and the related murder +support files (BitTornado, etc.). To upload the support files to the +tracker, seeder, and peers, run: + +```bash: +$ ansible-playbook -i prodction setup.yml +``` + +By default, these will go in `/usr/local/murder` in your apps deploy directory. +Override this by setting the variable `remote_murder_path`. + +Before deploying, you must start the tracker: + +```bash: +$ ansible-playbook -i prodction start_tracker.yml +``` + +At this point you should be able to deploy normally: + +```bash: +$ ansible-playbook -i prodction deploy.yml +``` + + +MANUAL USAGE (ansible-lssd without a deploy strategy) +----------------------------------------------------- + +Modify a ./production and ./group_vars/all, manually define servers: + +```INI:production +# ansible host +[ansible_host] +localhost ansible_connection=local + +# tracker node +[tracker] +10.0.0.1 + +# seeder node +[seeder] +10.0.0.1 + +# peer nodes +[peer] +10.1.1.1 +10.1.1.2 +10.1.1.3 +``` + +```YAML:group_vars/all +# deploy tag +tag: Deploy1 + +# path +seeder_files_path: ~/builds +destination_path: /opt/hoge # or some other directory +``` + +To distribute a directory of files, first make sure that murder is set +up on all hosts, then manually run the murder cap tasks: + +1. Start the tracker: + +```bash: +$ ansible-playbook -i prodction start_tracker.yml +``` + +2. Create a torrent from a directory of files on the seeder, and start seeding: + +```bash: +$ scp -r ./builds host1:~/builds +$ ansible-playbook -i prodction create_torrent.yml +$ ansible-playbook -i prodction start_seeder.yml +``` + +3. Distribute the torrent to all peers: + +```bash: +$ ansible-playbook -i prodction deploy.yml +``` +4. Stop the seeder and tracker: + +```bash: +$ ansible-playbook -i prodction stop_seeder_and_tracker.yml +``` + +When this finishes, all peers will have the files in /opt/hoge/Deploy1 + + diff --git a/create_torrent.yml b/create_torrent.yml index 30fe4bf..e1955f9 100644 --- a/create_torrent.yml +++ b/create_torrent.yml @@ -8,9 +8,3 @@ roles: - murder/create_torrent -- name: Start seeding - hosts: seeder - sudo: yes - roles: - - murder/start_seeding - diff --git a/deploy.yml b/deploy.yml index 406c66b..0fda5a9 100644 --- a/deploy.yml +++ b/deploy.yml @@ -1,11 +1,9 @@ - name: Deploy - hosts: - - peer - #- seeder + hosts: peer sudo: yes - #serial: 100 + serial: 1000 roles: - murder/peer diff --git a/production b/production index c964432..03894b1 100644 --- a/production +++ b/production @@ -18,5 +18,5 @@ localhost ansible_connection=local 10.1.1.3 10.1.1.4 10.1.1.[5:19] -10.2.1.[100:109] ansible_connection=ssh ansible_ssh_private_key_file=private.pem ansible_ssh_user=root +10.1.1.[100:109] ansible_connection=ssh ansible_ssh_private_key_file=private.pem ansible_ssh_user=root diff --git a/roles/admin/distribute_files/tasks/main.yml b/roles/admin/distribute_files/tasks/main.yml index db4ddfa..ad989e7 100644 --- a/roles/admin/distribute_files/tasks/main.yml +++ b/roles/admin/distribute_files/tasks/main.yml @@ -1,4 +1,6 @@ - +# SCPs a compressed version of all files from ./dist (the python Bittorrent library and custom scripts) to all server. +# The entire directory is sent, regardless of the role of each individual server. +# The path on the server is specified by remote_murder_path and will be cleared prior to transferring files over. - name: mkdir destination_path file: path={{ destination_path }} state=directory owner=root group=root mode=0755 tags: distribute_files diff --git a/roles/admin/start_tracker/tasks/main.yml b/roles/admin/start_tracker/tasks/main.yml index ced4d44..14a1b28 100644 --- a/roles/admin/start_tracker/tasks/main.yml +++ b/roles/admin/start_tracker/tasks/main.yml @@ -1,4 +1,4 @@ - +# Starts the Bittorrent tracker (essentially a mini-web-server) listening on port 8998. - name: start tracker shell: SCREENRC=/dev/null SYSSCREENRC=/dev/null screen -dmS murder_tracker python {{ remote_murder_path }}/murder_tracker.py && sleep 0.2 tags: start_tracker diff --git a/roles/admin/stop_all_peering/tasks/main.yml b/roles/admin/stop_all_peering/tasks/main.yml index 9c71279..db7625a 100644 --- a/roles/admin/stop_all_peering/tasks/main.yml +++ b/roles/admin/stop_all_peering/tasks/main.yml @@ -1,4 +1,5 @@ - +# Sometimes peers can go on forever (usually because of an error). +# This command will forcibly kill all "murder_client.py peer" commands that are running. - name: stop all peering shell: pkill -f "murder_client.py peer" register: result diff --git a/roles/admin/stop_all_seeding/tasks/main.yml b/roles/admin/stop_all_seeding/tasks/main.yml index e24f453..e5d359f 100644 --- a/roles/admin/stop_all_seeding/tasks/main.yml +++ b/roles/admin/stop_all_seeding/tasks/main.yml @@ -1,4 +1,4 @@ - +# Identical to stop_seeding, except this will kill all seeding processes. No 'tag' argument is needed." - name: stop all seeding shell: pkill -f "SCREEN.*seeder-" register: result diff --git a/roles/admin/stop_tracker/tasks/main.yml b/roles/admin/stop_tracker/tasks/main.yml index 7a93f65..bea475d 100644 --- a/roles/admin/stop_tracker/tasks/main.yml +++ b/roles/admin/stop_tracker/tasks/main.yml @@ -1,4 +1,4 @@ - +# If the Bittorrent tracker is running, this will kill the process. Note that if it is not running you will receive an error. - name: stop tracker shell: pkill -f 'SCREEN.*murder_tracker.py' register: result diff --git a/roles/murder/peer/tasks/main.yml b/roles/murder/peer/tasks/main.yml index 42abd10..2ef37d9 100644 --- a/roles/murder/peer/tasks/main.yml +++ b/roles/murder/peer/tasks/main.yml @@ -1,4 +1,12 @@ - +# Instructs all the peer servers to connect to the tracker and start download and spreading pieces and files amongst themselves. +# You must specify a valid 'tag' argument. +# Once the download is complete on a server, that server will fork the download process and seed for 30 seconds while returning control to Ansible. +# extract the files to the passed in 'destination_path' argument to destination_path/TAG/*. +# To not create this tag named directory, pass in the 'no_tag_directory=1' argument. +# If the directory is not empty, this command will fail. +# To clean it, pass in the 'unsafe_please_delete=1' argument. +# The compressed tgz in /{{ default_temp_path }} is never removed. +# When this task completes, all files have been transferred and moved into the requested directory. - name: set destination_path set_fact: destination_path={{ destination_path }}/{{ tag }} when: not no_tag_directory @@ -9,7 +17,7 @@ tags: peer - name: delete destination_path/* - shell: rm -rf '{{ destination_path }}a/*' + shell: rm -rf '{{ destination_path }}/*' when: unsafe_please_delete tags: peer diff --git a/roles/murder/start_seeding/tasks/main.yml b/roles/murder/start_seeding/tasks/main.yml index 0de460a..d7bec1f 100644 --- a/roles/murder/start_seeding/tasks/main.yml +++ b/roles/murder/start_seeding/tasks/main.yml @@ -1,4 +1,8 @@ +# Will cause the seeder machine to connect to the tracker and start seeding. +# The ip address returned by the 'host' bash command will be announced to the tracker. +# The server will not stop seeding until the stop_seeding task is called. +# You must specify a valid 'tag' argument (which identifies the .torrent in /tmp to use) - name: start seeding shell: SCREENRC=/dev/null SYSSCREENRC=/dev/null screen -dmS 'seeder-{{ tag }}' python {{ remote_murder_path }}/murder_client.py seeder '{{ filename }}.torrent' '{{ filename }}' {{ ansible_default_ipv4['address'] }} tags: start_seeding diff --git a/roles/murder/stop_seeding/tasks/main.yml b/roles/murder/stop_seeding/tasks/main.yml index 49f4428..4e74665 100644 --- a/roles/murder/stop_seeding/tasks/main.yml +++ b/roles/murder/stop_seeding/tasks/main.yml @@ -1,4 +1,7 @@ +# If the seeder is currently seeding, this will kill the process. +# If a peer was downloading from this seed, the peer will find another host to receive any remaining data. +# You must specify a valid 'tag' argument. - name: stop seeding shell: pkill -f "SCREEN.*seeder-{{ tag }}" register: result diff --git a/site.yml b/site.yml index d7fe910..6b16e3b 100644 --- a/site.yml +++ b/site.yml @@ -1,10 +1,11 @@ --- - include: setup.yml - include: stop_seeder_and_tracker.yml -- include: stop_all.yml +- include: stop_all_peers.yml - include: rm_tgz.yml - include: start_tracker.yml - include: create_torrent.yml +- include: start_seeder.yml - include: deploy.yml - include: stop_seeder_and_tracker.yml diff --git a/stop_all.yml b/stop_all_peers.yml similarity index 100% rename from stop_all.yml rename to stop_all_peers.yml diff --git a/stop_seeder_and_tracker.yml b/stop_seeder_and_tracker.yml index 3e2483f..58933b3 100644 --- a/stop_seeder_and_tracker.yml +++ b/stop_seeder_and_tracker.yml @@ -1,13 +1,12 @@ -- name: Stop seeding +- name: Stop seeder hosts: seeder sudo: yes roles: - - murder/stop_seeding + - admin/stop_seeder - name: Stop tracker hosts: tracker sudo: yes roles: - admin/stop_tracker - diff --git a/stop_tracker.yml b/stop_tracker.yml deleted file mode 100644 index 3e2483f..0000000 --- a/stop_tracker.yml +++ /dev/null @@ -1,13 +0,0 @@ - -- name: Stop seeding - hosts: seeder - sudo: yes - roles: - - murder/stop_seeding - -- name: Stop tracker - hosts: tracker - sudo: yes - roles: - - admin/stop_tracker -