1Metadata-Version: 1.1 2Name: ploy 3Version: 1.5.2 4Summary: A tool to manage servers through a central configuration. Plugins allow provisioning, configuration and other management tasks. 5Home-page: http://github.com/ployground/ploy 6Author: Florian Schulze 7Author-email: florian.schulze@gmx.net 8License: BSD 3-Clause License 9Description: Overview 10 ======== 11 12 Ploy is a commandline-tool to provision, manage and control server instances. 13 There are plugins for EC2 (ploy_ec2), FreeBSD Jails (ploy_ezjail) and more. 14 You can create, delete, monitor and ssh into instances while ploy handles the details like ssh fingerprint checking. 15 Additional plugins provide advanced functionality like integrating Fabric (ploy_fabric) and Ansible (ploy_ansible). 16 17 You can find the detailed documentation at http://ploy.readthedocs.org/en/latest/ 18 19 20 Installation 21 ============ 22 23 ploy is best installed with easy_install, pip or with zc.recipe.egg in a buildout. 24 It installs two scripts, ``ploy`` and ``ploy-ssh``. 25 26 27 Configuration 28 ============= 29 30 All information about server instances is located in ``ploy.conf``, which by default is looked up in ``etc/ploy.conf``. 31 32 33 Plugins 34 ======= 35 36 Support for backends and further functionality is implemented by plugins. One plugin is included with ploy. 37 38 ``plain`` 39 For regular servers accessible via ssh. 40 41 You can see which plugins are available in your current installation with ``ploy -v``. 42 43 44 Plain 45 ----- 46 47 With plain instances you can put infos about servers into the configuration to benefit from some ploy features like ssh fingerprint checking and plugins like the Fabric integration. 48 49 50 Options 51 ~~~~~~~ 52 53 ``host`` or ``ip`` 54 (**required**) The host name or address for the server. 55 56 ``user`` 57 The default user for ssh connections. If it's set to ``*`` then the current 58 local user name is used. 59 60 ``port`` 61 The ssh port number. 62 63 ``ssh-host-keys`` or ``ssh-fingerprints`` 64 (**required**) The public ssh host keys (or fingerprints) of the server. 65 66 ``ssh-host-keys`` 67 It's best to use the public ssh host keys if available. 68 You can either specify the path, or put in the contents directly (``ssh-rsa AAAA...``). 69 Multiple host keys can be specified one per line, or separated by commas. 70 71 ``ssh-fingerprints`` 72 If set to ``ask`` then manual interactive verification is enabled. 73 If set to ``ignore`` then no verification is performed at all! 74 Multiple fingerprints can be specified one per line, or separated by commas. 75 The format of fingerprints is either 16 bytes as hex numbers separated by colons, 76 the same 16 bytes prefixed by ``MD5:``, 77 or the hash type, followed by a colon and the base 64 encoded hash digest. 78 79 ``password-fallback`` 80 If this boolean is true, then using a password as fallback is enabled if the 81 ssh key doesn't work. This is off by default. 82 You may be asked more than once for the password. 83 The first time is by paramiko which always happens, but is remembered. 84 The other times is by the ssh command line tool if it's invoked. 85 86 ``password`` 87 Never use this directly! If password-fallback is enabled this password is 88 used. This is mainly meant for Fabric scripts which have other ways to get 89 the password. On use case is bootstrapping `FreeBSD <http://www.freebsd.org/>`_ 90 from an `mfsBSD <http://mfsbsd.vx.sk/>`_ distribution where the password is 91 fixed. 92 93 ``proxycommand`` 94 The command to use in the ProxyCommand option for ssh when using the ``ploy-ssh`` 95 command. There are some variables which can be used: 96 97 ``path`` 98 The directory of the ploy.conf file. Useful if you want to use the ``ploy-ssh`` 99 command itself for the proxy. 100 101 ``known_hosts`` 102 The absolute path to the known_hosts file managed by ploy. 103 104 ``instances`` 105 The variables of other instances. For example: instances.foo.ip 106 107 In addition to these the variables of the instance itself are available. 108 109 A full example for a proxycommand:: 110 111 proxycommand = {path}/../bin/ploy-ssh vm-master -W {ip}:22 112 113 ``ssh-key-filename`` 114 Location of private ssh key to use. 115 116 ``ssh-extra-args`` 117 A list of settings separated by newlines passed on to ssh. 118 119 Example:: 120 121 ssh-extra-args = ForwardAgent yes 122 123 124 SSH integration 125 =============== 126 127 ploy provides an additional tool ``ploy-ssh`` to easily perform SSH based 128 operations against named instances. Particularly, it encapsulates the 129 entire *SSH fingerprint* mechanism. For example EC2 instances are often 130 short-lived and normally trigger warnings, especially, if you are using 131 elastic IPs. 132 133 Note:: it does so not by simply turning off these checks, but by transparently updating its own fingerprint list using mechanisms provided by the backend plugins. 134 135 The easiest scenario is simply to create an SSH session with an instance. You 136 can either use the ssh subcommand of the ploy tool like so:: 137 138 ploy ssh INSTANCENAME 139 140 Alternatively you can use the ploy-ssh command directly, like so:: 141 142 ploy-ssh INSTANCENAME 143 144 The latter has been provided to support scp and rsync. Here are some 145 examples, you get the idea:: 146 147 scp -S `pwd`/bin/ploy-ssh some.file demo-server:/some/path/ 148 rsync -e "bin/ploy-ssh" some/path fschulze@demo-server:/some/path 149 150 151 Instance names 152 ============== 153 154 Instances have an **id** which is the part after the colon in the configuration. 155 They also have a **unique id** which has the form ``[masterid]-[instanceid]``. 156 The ``[masterid]`` depends on the plugin. 157 For plain instances it is ``plain``. 158 The ``[instanceid]`` is the **id** of the instance. 159 So, if you have the following config:: 160 161 [plain-instance:foo] 162 ... 163 164 Then the **unique id** of the instance is ``plain-foo``. 165 166 167 Macro expansion 168 =============== 169 170 In the ``ploy.conf`` you can use macro expansion for cleaner configuration 171 files. That looks like this:: 172 173 [ec2-instance:demo-server2] 174 <= demo-server 175 securitygroups = demo-server2 176 177 [ec2-securitygroup:demo-server2] 178 <= demo-server 179 180 All the options from the specified macro are copied with some exceptions depending on the backend plugin. 181 182 If you want to copy data from some other kind of options, you can add a colon 183 in the macro name. This is useful if you want to have a base for instances 184 like this:: 185 186 [macro:base-instance] 187 keypair = default 188 region = eu-west-1 189 placement = eu-west-1a 190 191 [ec2-instance:server] 192 <= macro:base-instance 193 ... 194 195 196 Massaging of config values 197 ========================== 198 199 Plugins and ploy massage certain string values from the config to convert them to other types and do formatting or expansion. 200 201 You can use that yourself, which is useful for the Fabric integration and other things. 202 203 Here is a simple example:: 204 205 [section] 206 massagers = 207 intvalue=ploy.config.IntegerMassager 208 boolvalue=ploy.config.BooleanMassager 209 intvalue = 1 210 boolvalue = yes 211 212 If you now access those values from for example a fabric task, you get the correct type instead of strings. 213 214 The above syntax registers the massagers only for that section. 215 You can register massagers for other sections or even section groups with this syntax:: 216 217 massagers = 218 [option]=[sectiongroup]:import.path.to.massager 219 [option]=[sectiongroup]:[section]:import.path.to.massager 220 221 The parts have the following meaning: 222 223 ``[option]`` 224 This is the name of the option which should be massaged 225 226 ``[sectiongroup]`` 227 The name of the section group. 228 That's the part before the optional colon in a section. 229 To match sections without a colon, use ``global``. 230 To match every section, use ``*``. 231 232 ``[section]`` 233 The name of the section to which this massager is applied. 234 If empty, the current section is used. 235 236 237 Buildout specifics 238 ================== 239 240 With zc.recipe.egg you can set a custom configfile location like this:: 241 242 [ploy] 243 recipe = zc.recipe.egg 244 eggs = ploy 245 arguments = configpath="${buildout:directory}/etc/", configname="servers.cfg" 246 247 248 Changelog 249 ========= 250 251 1.5.2 - 2018-08-20 252 ------------------ 253 254 * Stop testing on Python 3.3. 255 [fschulze] 256 257 * Fix multiple masters for ``instance``. 258 [fschulze] 259 260 261 1.5.1 - 2017-12-17 262 ------------------ 263 264 * Fix getting fingerprints automatically when ``ssh-host-keys`` is used. 265 [fschulze] 266 267 268 1.5.0 - 2017-10-03 269 ------------------ 270 271 * New ``ssh-host-keys`` option which allows to set host keys directly to 272 force paramiko to use a specific key type to avoid fingerprint mismatches. 273 [fschulze] 274 275 276 1.4.0 - 2017-10-02 277 ------------------ 278 279 * Allow instance implementations to return multiple fingerprints via 280 ``get_fingerprints`` method. 281 [fschulze] 282 283 * Support other key types than just rsa, because paramiko > 2 defaults to 284 ``ed25519``. 285 [fschulze] 286 287 * Output more information about used keys on fingerprint mismatch. 288 [fschulze] 289 290 291 1.3.1 - 2016-06-02 292 ------------------ 293 294 * Don't get ``ssh-fingerprints`` from master if not set in instance config. 295 This fixes automatic fingerprint fetching for EC2, ezjail etc. 296 [fschulze] 297 298 299 1.3.0 - 2016-05-21 300 ------------------ 301 302 * Add option ``ssh-fingerprints`` which allows to specify multiple fingerprints. 303 [fschulze] 304 305 * Support new output of ``ssh-keygen`` which includes the hash type and 306 defaults to ``SHA256``. 307 [fschulze] 308 309 310 1.2.1 - 2015-08-27 311 ------------------ 312 313 * Allow to specify multiple masters per instance. 314 [fschulze] 315 316 317 1.2.0 - 2015-03-05 318 ------------------ 319 320 * Add ``Executor`` helper to handle local and remote command execution. It's 321 also handling ssh agent forwarding enabled by either the users ssh config 322 or the ``ssh-extra-args`` option. 323 [fschulze] 324 325 326 1.1.0 - 2015-02-28 327 ------------------ 328 329 * Add ``ssh-extra-args`` option. 330 [fschulze] 331 332 * Add ``annotate`` command to print the configuration with the source of each 333 setting. 334 [fschulze] 335 336 * Allow custom shebang in gzipped startup scripts. 337 [fschulze] 338 339 340 1.0.3 - 2015-01-22 341 ------------------ 342 343 * Drop bad entries from our ``known_hosts`` file to prevent failures 344 in paramiko. 345 [fschulze] 346 347 * Set ``StrictHostKeyChecking=yes`` for all ssh connections to prevent 348 interactive asking. 349 [fschulze] 350 351 352 1.0.2 - 2014-10-04 353 ------------------ 354 355 * Ask before terminating an instance. 356 [fschulze] 357 358 * Fix config setting propagation in some cases of proxied instances. 359 [fschulze] 360 361 * Close all connections before exiting. This prevents hangs caused by open 362 proxy command threads. 363 [fschulze] 364 365 * Add option to log debug output. 366 [fschulze] 367 368 * Add helpers to setup proxycommand in plugins. 369 [fschulze] 370 371 372 1.0.1 - 2014-08-13 373 ------------------ 374 375 * Fix error output for plain instances on ssh connection failures. 376 [fschulze] 377 378 379 1.0.0 - 2014-07-19 380 ------------------ 381 382 * Fix removal of bad host keys when using non standard ssh port. 383 [fschulze] 384 385 * Renamed ``plain-master`` to ``plain``, so the uids of instances are nicer. 386 [fschulze] 387 388 389 1.0rc15 - 2014-07-16 390 -------------------- 391 392 * Only remove bad host key from known_hosts instead of clearing it completely. 393 [fschulze] 394 395 * Removed support for ``proxyhost`` option. It caused hangs and failures on 396 missing or invalid ssh fingerprints. 397 [fschulze] 398 399 * Allow empty ``startup_script`` option to mean use no startup script. 400 [fschulze] 401 402 403 1.0rc14 - 2014-07-15 404 -------------------- 405 406 * Allow ``fingerprint`` to be set to a public host key file. 407 [fschulze] 408 409 410 1.0rc13 - 2014-07-08 411 -------------------- 412 413 * Better error message for instances missing because the plugin isn't installed. 414 [fschulze] 415 416 * Fix tests when ploy itself isn't installed. 417 [fschulze] 418 419 420 1.0rc12 - 2014-07-08 421 -------------------- 422 423 * Use plain conftest.py instead of pytest plugin. 424 [fschulze] 425 426 427 1.0rc11 - 2014-07-05 428 -------------------- 429 430 * Fix uid method for master instances. 431 [fschulze] 432 433 434 1.0rc10 - 2014-07-04 435 -------------------- 436 437 * Print plugin versions with ``-v`` and ``--versions``. 438 [fschulze] 439 440 * Python 3 compatibility. 441 [fschulze] 442 443 444 1.0rc9 - 2014-06-29 445 ------------------- 446 447 * Let plugins add type of lists to show with the ``list`` command. 448 [fschulze] 449 450 * Use ``server`` and ``instance`` consistently. 451 [fschulze] 452 453 * Always make instances accessible by their full name in the form of 454 "[master_id]-[instance_id]". Only if there is no conflict, the short version 455 with just "[instance_id]" is also available for convenience. 456 [fschulze] 457 458 * Add instance id validator which limits to letters, numbers, dashes and 459 underscores. 460 [fschulze] 461 462 * Renamed from mr.awsome to ploy. 463 [fschulze] 464 465 466 1.0rc8 - 2014-06-16 467 ------------------- 468 469 * Give a bit more info on ssh connection failures. 470 [fschulze] 471 472 473 1.0rc7 - 2014-06-11 474 ------------------- 475 476 * Expose some test fixtures for reuse in plugins. 477 [fschulze] 478 479 * Add before_terminate and after_start hooks and make it simple for plugins 480 to add their own hooks. 481 [fschulze] 482 483 484 1.0rc6 - 2014-06-10 485 ------------------- 486 487 * Add ``get_path`` method to ConfigSection class. 488 [fschulze] 489 490 491 1.0rc5 - 2014-06-09 492 ------------------- 493 494 * Provide helper method ``ssh_args_from_info`` on BaseInstance to get the 495 arguments for running the ssh executable from the info provided by 496 init_ssh_key. 497 [fschulze] 498 499 * Allow overwriting the command name in help messages for bsdploy. 500 [fschulze] 501 502 * Make debug command usable for instances that don't have a startup script. 503 [fschulze] 504 505 * Instances can provide a get_port method to return a default port. 506 [fschulze] 507 508 * Catch socket errors in init_ssh_key of plain instances to print additional 509 info for debugging. 510 [fschulze] 511 512 * Delay setting of config file path to expose too early use of config in 513 plugins. Refs #29 514 [fschulze] 515 516 517 1.0rc4 - 2014-05-21 518 ------------------- 519 520 * Fix massagers for ``[instance:...]`` sections. 521 [fschulze] 522 523 * Copy massagers in ConfigSection.copy, so overrides in startup script work 524 correctly. 525 [fschulze] 526 527 528 1.0rc3 - 2014-05-15 529 ------------------- 530 531 * Fetch fingerprints only when necessary. This speeds up connections when the 532 fingerprint in known_hosts is still valid. 533 [fschulze] 534 535 536 1.0rc2 - 2014-05-14 537 ------------------- 538 539 * Moved setuptools-git from setup.py to .travis.yml, it's only needed for 540 releases and testing. 541 [fschulze] 542 543 * More tests. 544 [fschulze] 545 546 547 1.0rc1 - 2014-03-23 548 ------------------- 549 550 * Test, enhance and document adding massagers via config. 551 [fschulze] 552 553 * Moved ec2 and fabric integration into separate plugins. 554 [fschulze] 555 556 * You can now have instances with the same name if the belong to different 557 masters, they will then get the name of the master as a prefix to their name. 558 [fschulze] 559 560 * Add possibility to overwrite the default config name. 561 [tomster] 562 563 * Improved ``proxycommand`` and documented it. 564 [fschulze] 565 566 * Make the AWS instance available in masters. This changes the ``get_masters`` 567 plugin interface. 568 [fschulze] 569 570 * Use os.execvp instead of subprocess.call. This allows the use of ``assh`` in 571 the ``proxycommand`` option, which greatly simplifies it's use. 572 [fschulze] 573 574 * Added command plugin hooks. 575 [fschulze] 576 577 * The variable substitution for the ``proxycommand`` option now makes the other 578 instances available in a dict under ``instances``. And adds ``known_hosts``. 579 [fschulze] 580 581 * Load plugins via entry points instead of the ``plugin`` section in the config. 582 [fschulze] 583 584 * Allow fallback to password for ssh to plain instances. 585 [fschulze] 586 587 * Add option to ask for manual fingerprint validation for plain instances. 588 [fschulze] 589 590 591 0.13 - 2013-09-20 592 ----------------- 593 594 * Use os.path.expanduser on all paths, so that one can use ~ in config values 595 like the aws keys. 596 [fschulze] 597 598 599 0.12 - 2013-09-11 600 ----------------- 601 602 * There is no need to add the AWS account id to security group names anymore. 603 [fschulze] 604 605 * Rules are removed from security groups if they aren't defined in the config. 606 [fschulze] 607 608 * Allow adding of custom config massagers from inside the config. 609 [fschulze] 610 611 * Support block device maps to enable use of more than one ephemeral disk. 612 [fschulze] 613 614 * Added ``do`` method on ec2 and plain instances which allows to call fabric 615 commands. 616 [fschulze] 617 618 * Use PathMassager for ``access-key-id`` and ``secret-access-key`` in the 619 ``ec2-master`` section. This might break existing relative paths for these 620 options. 621 [fschulze] 622 623 * Added support for EBS boot instances. 624 [fschulze] 625 626 * Add option ``ssh-key-filename`` to point to a private ssh key for ec2 and 627 plain instances. 628 [fschulze] 629 630 * Fix Fabric integration for newer versions of Fabric. 631 [fschulze] 632 633 * Support ``proxycommand`` option for plain instances. This also caused a 634 change in the ``init_ssh_key`` API for plugins. 635 [fschulze] 636 637 * Support ``ProxyCommand`` from ``~/.ssh/config`` for plain instances. 638 Requires Fabric 1.5.0 and Paramiko 1.9.0 or newer. 639 [fschulze] 640 641 642 0.11 - 2012-11-08 643 ----------------- 644 645 * Support both the ``ssh`` and ``paramiko`` libraries depending on which 646 Fabric version is used. 647 [fschulze] 648 649 650 0.10 - 2012-06-04 651 ----------------- 652 653 * Added ``ec2-connection`` which helps in writing Fabric scripts which don't 654 connect to a server but need access to the config and AWS (like uploading 655 something to S3). 656 [fschulze] 657 658 * Fix several problems with using a user name other than ``root`` for the 659 ``do`` and ``ssh`` commands. 660 [fschulze] 661 662 * Require Fabric >= 1.3.0. 663 [fschulze] 664 665 * Require boto >= 2.0. 666 [fschulze] 667 668 * Added hook for startup script options. 669 [fschulze] 670 671 * Added possibility to configure hooks. 672 [fschulze] 673 674 * Refactored to enable plugins for different virtualization or cloud providers. 675 [fschulze] 676 677 * Added lots of tests. 678 [fschulze] 679 680 681 0.9 - 2010-12-09 682 ---------------- 683 684 * Overwrites now also affect server creation, not just the startup script. 685 [fschulze] 686 687 * Added ``list`` command which supports just listing ``snapshots`` for now. 688 [fschulze] 689 690 * Added ``delete-volumes-on-terminate`` option to delete volumes created from 691 snapshots on instance termination. 692 [fschulze] 693 694 * Added support for creating volumes from snapshots on instance start. 695 [natea, fschulze] 696 697 * Added support for ``~/.ssh/config``. This is a bit limited, because the 698 paramiko config parser isn't very good. 699 [fschulze] 700 701 * Added ``help`` command which provides some info for zsh autocompletion. 702 [fschulze] 703 704 0.8 - 2010-04-21 705 ---------------- 706 707 * For the ``do`` command the Fabric options ``reject_unknown_hosts`` and 708 ``disable_known_hosts`` now default to true. 709 [fschulze] 710 711 * Allow adding normal servers to use with ``ssh`` and ``do`` commands. 712 [fschulze] 713 714 * Refactored ssh connection handling to only open network connections when 715 needed. Any fabric option which doesn't need a connection runs right away 716 now (like ``-h`` and ``-l``). 717 [fschulze] 718 719 * Fix status output after ``start``. 720 [fschulze] 721 722 0.7 - 2010-03-22 723 ---------------- 724 725 * Added ``snapshot`` method to Server class for easy access from fabfiles. 726 [fschulze] 727 728 0.6 - 2010-03-18 729 ---------------- 730 731 * It's now possible to specify files which contain the aws keys in the 732 ``[aws]`` section with the ``access-key-id`` and ``secret-access-key`` 733 options. 734 [fschulze] 735 736 * Added ``-c``/``--config`` option to specify the config file to use. 737 [fschulze] 738 739 * Added ``-v``/``--version`` option. 740 [tomster (Tom Lazar), fschulze] 741 742 * Comment lines in the startup script are now removed before any variables 743 in it are expanded, not afterwards. 744 [fschulze] 745 746 * Use argparse library instead of optparse for more powerful command line 747 parsing. 748 [fschulze] 749 750 0.5 - 2010-03-11 751 ---------------- 752 753 * Added gzipping of startup script by looking for ``gzip:`` prefix in the 754 filename. 755 [fschulze] 756 757 * Added macro expansion similar to zc.buildout 1.4. 758 [fschulze] 759 760 0.4 - 2010-02-18 761 ---------------- 762 763 * Check console output in ``status`` and tell user about it. 764 [fschulze] 765 766 * Friendly message instead of traceback when trying to ssh into an unavailable 767 server. 768 [fschulze] 769 770 * Remove comment lines from startup script if it's starting with ``#!/bin/sh`` 771 or ``#!/bin/bash``. 772 [fschulze] 773 774 * Removed ``-r`` option for ``start`` and ``debug`` commands and replaced it 775 with more general ``-o`` option. 776 [fschulze] 777 778 * Made startup script optional (not all AMIs support it, especially Windows 779 ones). 780 [fschulze] 781 782 * The ``stop`` command actually only stops an instance now (only works with 783 instances booted from an EBS volume) and the new ``terminate`` command now 784 does what ``stop`` did before. 785 [fschulze] 786 787 * Better error message when no console output is available for ssh finger 788 print validation. 789 [fschulze] 790 791 * Fixed indentation in documentation. 792 [natea (Nate Aune), fschulze] 793 794 0.3 - 2010-02-08 795 ---------------- 796 797 * Removed the ``[host_string]`` prefix of the ``do`` command output. 798 [fschulze] 799 800 0.2 - 2010-02-02 801 ---------------- 802 803 * Snapshots automatically get a description with date and volume id. 804 [fschulze] 805 806 * The ssh command can now be used with scp and rsync. 807 [fschulze] 808 809 810 0.1 - 2010-01-21 811 ---------------- 812 813 * Initial release 814 [fschulze] 815 816Platform: UNKNOWN 817Classifier: Environment :: Console 818Classifier: Intended Audience :: System Administrators 819Classifier: Programming Language :: Python :: 2.6 820Classifier: Programming Language :: Python :: 2.7 821Classifier: Programming Language :: Python :: 3.3 822Classifier: Programming Language :: Python :: 3.4 823Classifier: Programming Language :: Python :: 3.5 824Classifier: Programming Language :: Python :: 3.6 825Classifier: Topic :: System :: Installation/Setup 826Classifier: Topic :: System :: Systems Administration 827