..::[ The Bitcoin Foundation: V Users Manual ]::.. Doc Version: 99996 K Author: mod6 Fingerprint: 0x027A8D7C0FB8A16643720F40721705A8B71EADAF 0x00]: Introduction Welcome to V! This document is intended to be a users manual for mod6's perl implementation of V. Contained herein the user will find usage explanations and examples of the many options available. 0x01]: Getting Started [ Check if perl is installed & version ]: First, in order to execute the perl version of V, the user must have perl version 5.005 or greater installed on the local UNIX environment. Perl typically comes installed on many UNIX environments ahead of time, but just to be sure, do the following from the command prompt: perl --version The user should see a lengthy version message that starts with something like this: `This is perl 5, version 18, subversion 2 (v5.18.2) ...' If not, please install perl 5.005 or greater before going any further: Ubuntu: apt-get install -y perl Gentoo: emerge =perl-5.20.2.ebuild [ Install CPAN ]: If it is desired to at all use the graphing feature of V the user will need to install CPAN [ `cpan` or `cpanm` or on gentoo, `g-cpan` ] so that the Graph::Easy perl library can be installed. Ubuntu: apt-get install cpanminus cpanm -i Graph::Easy Gentoo [x86-64]: emerge g-cpan [ NOTE: Copy the next nine lines exacty as they are presented here and ] [ then paste them into the shell. ] cat < /etc/portage/package.accept_keywords # required by perl-gcpan/JSON-MaybeXS-1.003005::x-g-cpan # required by JSON-MaybeXS (argument) =dev-perl/Test-Without-Module-0.180.0 ~amd64 # required by perl-gcpan/Cpanel-JSON-XS-3.0115::x-g-cpan # required by Cpanel-JSON-XS (argument) =dev-perl/common-sense-3.730.0 ~amd64 EOF g-cpan -i Graph::Easy [ Install GnuPG ]: The user will need GnuPG installed locally to run V, if you already have this installed, skip this step. Ubuntu: sudo apt-get install -y gnupg [NOTE: 1.4.19 seems to be the oldest portage a recent gentoo ships with)]: Gentoo: emerge =gnupg-1.4.19 [ Install wget ]: Many UNIX systems come with `wget` installed already, if yours does not, install it: Ubuntu: sudo apt-get install -y wget Gentoo: emerge wget [ Install GraphViz ]: In addition to Graph::Easy, if you wish to have V automatically build the SVG graph in an HTML output file for you from the Dot language output file, also output by V, you need to install GraphViz. Ubuntu: sudo apt-get install -y graphviz Gentoo: emerge -a graphviz etc-update [ enter -5 when prompted ] emerge -a graphviz [ Answer Yes at prompt ] [ Download V Archive ]: Now you must obtain the V archive & signature from: http://thebitcoin.foundation/v/V-20160128.tar.gz http://thebitcoin.foundation/v/V-20160128.tar.gz.mod6.sig Then check the PGP signatures supplied: wget http://mod6.net/mod6.asc -O mod6.asc gpg --import mod6.asc [ Key Fingerprint: 0x027A8D7C0FB8A16643720F40721705A8B71EADAF ] gpg --verify V-20160128.tar.gz.mod6.sig V-20160128.tar.gz Then unpack the archive: tar -xf V-20160128.tar.gz [ Start V for the first time ]: First, set the executable bit on v.pl: chmod 0755 v.pl Before you get any further, create a '.wot' directory (V looks for '.wot' in the current working directory by default) and populate it with PGP public keys manually. Name the pubkey files as such: .asc For example: mod6.asc Now have V sync the required Seals and Patches directories from a signed mirror. To view the list of mirrors, run the following command, the output you'll see below. ./v.pl m v_mirrors Mirrors signed by (mod6): http://thebitcoin.foundation As stated from mirrors output we can use URL from The Bitcoin Foundation to sync V up-to-date with all the latest WoT entries (PGP Public Keys), VPatch Signatures (Seals) and Vpatches. To begin this initial sync do the following: ./v.pl i http://thebitcoin.foundation 0x01]: V Usage At this point the user has installed all of V's requirements, performed a lookup of available signed mirrors, and sync'd the WoT, Patches and Seals. What follows are usages and definitions of V's options with examples. A note about option syntax. Any option enclosed with parenthesis ( ) is required. The | separates any aliases of commands. Square brackets [ ] denote optional options. Angle brackets < > denote required arguments to a given command. [ m | mirrors ]: Arguments: () The m or mirrors command is available to connect to the main V site: http://thebitcoin.foundation Here, V can connect and pull the list of available mirrors, signed by mirror administrators with L1 trust with assbot and are in good standing in the WoT. Ask mod6 about this if you want to run an authorized, signed mirror of V. The mirrors command takes one required argument, an output directory for the list of mirrors and the signatures so V can verify the list. Example: ./v.pl m v_mirrors Mirrors signed by (mod6): http://thebitcoin.foundation [ i | init ]: Arguments & Options: (mirror_url) [( )] The i or init command is intended to be utilized the first time running V on an environment. It takes one required option, and two optional options. The required argument is a V mirror URL to sync from. Next, the user can choose to use the default Patches ('patches' in the current working directory) and Seals (.seals in the current working directory) directories by not setting the two or options -- only passing a mirror URL argument to the init command. If the user wishes to use their own named directories, simply pass in those arguements in the exact order specified. Example: ./v.pl i http://thebitcoin.foundation Full vpatch sync complete to "/home/mod6/patches" Seal sync complete to "/home/mod6/.seals" Example: ./v.pl i http://thebitcoin.foundation wot vpatches seals Full vpatch sync complete to "vpatches" Seal sync complete to "seals" [ wd | wotdir ]: Arguments: () The wd or wotdir command is available to point V at a specific WoT directory rather than the default: '.wot' (in the current working directory) There is one required argument: a WoT directory. Example case, only mod6.asc exists in wot2: ./v.pl f wd wot2 genesis.vpatch (mod6) bitcoin-asciilifeform.1.vpatch (mod6) rm_rf_upnp.vpatch (mod6) ... [ pd | patchdir ]: Arguments: () The pd or patchdir command is available to point V at a specific patch directory rather than the default: 'patches', in V's present working directory. There is one required argument: a vpatches directory. Example case, only genesis.vpatch exists in patches2: ./v.pl f pd patches2 genesis.vpatch (asciilifeform, mircea_popescu, mod6, trinque) [ sd | sealdir ]: Arguments: () The sd or sealdir command is available to point V at a specific seal directory rather than the default: '.seals' (in the current working directory) There is one required argument: a seals directory. Example case, only seals created by mod6 exist in seal2: ./v.pl f sd seals2/ genesis.vpatch (mod6) bitcoin-asciilifeform.1.vpatch (mod6) rm_rf_upnp.vpatch (mod6) ... [ w | wot ]: Options: [ finger ] The w or wot command will build a list of WoT entities eligable for creating seals for approved vpatches. If a specific vpatch has not been signed by a WoT entity, it is considered a 'WILD' vpatch. A vpatch must be signed by both Co-Chairs of The Bitcoin Foundation to be considered approved for release. Example: ./v.pl w asciilifeform:17215D118B7239507FAFED98B98228A001ABFFC7:Stanislav Datskovskiy ben_vulpes:4F7907942CA8B89B01E25A762AFA1A9FD2D031DA:Ben Vulpes mircea_popescu:6160E1CAC8A3C52966FD76998A736F0E2FB7B452:Mircea Popescu (Acest articol are apriori avantajul aliteralitatii alaturi.) mod6:027A8D7C0FB8A16643720F40721705A8B71EADAF:mod6 (mod6) punkman:F28E0095843B91CB22E7D65533588BE08B232B13:punkman trinque:FC66C0C5D98C42A1D4A98B6B42F9985AFAB953C4:Michael Trinque ./v.pl w finger asciilifeform-B98228A001ABFFC7:17215D118B7239507FAFED98B98228A001ABFFC7:Stanislav Datskovskiy ben_vulpes-2AFA1A9FD2D031DA:4F7907942CA8B89B01E25A762AFA1A9FD2D031DA:Ben Vulpes mircea_popescu-8A736F0E2FB7B452:6160E1CAC8A3C52966FD76998A736F0E2FB7B452:Mircea Popescu (Acest articol are apriori avantajul aliteralitatii alaturi.) mod6-721705A8B71EADAF:027A8D7C0FB8A16643720F40721705A8B71EADAF:mod6 (mod6) punkman-33588BE08B232B13:F28E0095843B91CB22E7D65533588BE08B232B13:punkman trinque-42F9985AFAB953C4:FC66C0C5D98C42A1D4A98B6B42F9985AFAB953C4:Michael Trinque [ r | roots ]: The r or roots command takes no options or arguments, unless a different pd or patchdir is specified. It simply traverses the vpatch directories contained vpatches and returns any root vpatches found in the topological order. Examples: ./v.pl r Root: genesis.vpatch (asciilifeform, mircea_popescu, mod6, trinque) Examples: ./v.pl r pd patches2 Root: genesis.vpatch (asciilifeform, mircea_popescu, mod6, trinque) [ l | leafs ]: The l or leafs command takes no options or arguments, unless a different pd or patchdir is specified. It simply traverses the vpatch directories contained vpatches and returns any leaf vpatches found in the topological order. Examples: ./v.pl l Leaf: asciilifeform_add_verifyall_option.vpatch (asciilifeform, mod6) Leaf: asciilifeform_maxint_locks_corrected.vpatch (asciilifeform, mod6) Example case, only genesis.vpatch exists in patches2: ./v.pl l pd patches2 Leaf: genesis.vpatch (asciilifeform, mircea_popescu, mod6, trinque) [ f | flow ]: The f or flow command prints a topoligical flow of vpatches based on precedence. By default will look for the 'patches' directory in the present working directory of V and print the flow to stdout. Example: ./v.pl f genesis.vpatch (asciilifeform, mircea_popescu, mod6, trinque) bitcoin-asciilifeform.1.vpatch (asciilifeform, mod6) rm_rf_upnp.vpatch (asciilifeform, mod6) bitcoin-asciilifeform.3-turdmeister-alert-snip.vpatch (asciilifeform, mod6) bitcoin-asciilifeform.2-https_snipsnip.vpatch (asciilifeform, mod6) bitcoin-asciilifeform.4-goodbye-win32.vpatch (asciilifeform, mod6) asciilifeform_dnsseed_snipsnip.vpatch (asciilifeform, mod6) asciilifeform_zap_hardcoded_seeds.vpatch (asciilifeform, mod6) asciilifeform-kills-integer-retardation.vpatch (asciilifeform, mod6) asciilifeform_zap_showmyip_crud.vpatch (asciilifeform, mod6) asciilifeform_dns_thermonyukyoolar_kleansing.vpatch (asciilifeform, mod6) asciilifeform_and_now_we_have_block_dumper_corrected.vpatch (asciilifeform, mod6) mod6_fix_dumpblock_params.vpatch (asciilifeform, mod6) bitcoin-v0_5_3_1-static_makefile_v002.8.vpatch (asciilifeform, mod6) bitcoin-v0_5_3_1-rev_bump.7.vpatch (asciilifeform, mod6) asciilifeform_ver_now_5_4_and_irc_is_gone_and_now_must_give_ip.vpatch (asciilifeform, mod6) asciilifeform_orphanage_thermonuke.vpatch (asciilifeform, mod6) asciilifeform_and_now_we_have_eatblock.vpatch (asciilifeform, mod6) bitcoin-v0_5_3-db_config.6.vpatch (asciilifeform, mod6) asciilifeform_tx-orphanage_amputation.vpatch (asciilifeform, mod6) asciilifeform_maxint_locks_corrected.vpatch (asciilifeform, mod6) asciilifeform_lets_lose_testnet.vpatch (asciilifeform, mod6) asciilifeform_add_verifyall_option.vpatch (asciilifeform, mod6) Example case, only genesis.vpatch exists in patches2: ./v.pl f pd patches2 genesis.vpatch (asciilifeform, mircea_popescu, mod6, trinque) [ p | press ]: Arguments: ( ) The p or press command is available to apply vpatches up through in topological order (see flow command) to an output directory . There are two required arguments; an output directory for applied patches and a vpatch as the tip of the tree to press up through. By default, no output is shown; however if the user supplies `v' or `verbose' directly after the p or press command then the output from the patching applcation process will be directed to stdout. Example: ./v.pl p press_output genesis.vpatch Example: ./v.pl p verbose press_verbose genesis.vpatch genesis.vpatch patching file bitcoin/.gitignore patching file bitcoin/COPYING patching file bitcoin/src/base58.h patching file bitcoin/src/bignum.h patching file bitcoin/src/bitcoinrpc.cpp patching file bitcoin/src/bitcoinrpc.h patching file bitcoin/src/checkpoints.cpp patching file bitcoin/src/checkpoints.h patching file bitcoin/src/crypter.cpp patching file bitcoin/src/crypter.h patching file bitcoin/src/db.cpp patching file bitcoin/src/db.h patching file bitcoin/src/headers.h patching file bitcoin/src/init.cpp ... [ ss | sync-seals ]: Arguments: ( ) The ss or sync-seals command is avilable to allow the user to sync seal to an alternative directory. Two arguments are required; the from which to sync and the alternative or existing seals directory . Example: ./v.pl ss http://thebitcoin.foundation seals2 Seal sync complete to "seals2" [ sv | sync-vpatches ]: Arguments: ( ... ) The sv or sync-vpatches command is availabe to allow the user to sync one or more individual vpatches to a alternative output directory. Three arguments are required; the from which to sync, the alternative or existing directory and one or more . Example case, sync one vpatch to an existing patches directory: ./v.pl sv http://thebitcoin.foundation patches genesis.vpatch genesis.vpatch sync complete to "patches" Example case, sync more than one vpatch to an alternative patches directory: ./v.pl sv http://thebitcoin.foundation patches2 genesis.vpatch rm_rf_upnp.vpatch genesis.vpatch sync complete to "patches2" rm_rf_upnp.vpatch sync complete to "patches2" [ sa | sync-all-vpatches ]: Arguments: ( ) The sa or sync-all-vpatches command is avilable to allow the user to sync all vpatches from a given mirror to an alternative output directory. Two arguments are required; the from which to sync and the alternative or existing patches directory . Example case, sync all vpatches to the pre-existing patches directory: ./v.pl sa http://thebitcoin.foundation patches Full vpatch sync complete to "patches" Example case, sync all vpatches to an alternative patches directory: ./v.pl sa http://thebitcoin.foundation patches2 Full vpatch sync complete to "patches2" [ se | sync-everything ]: Arguments: ( ) The se or sync-everything command is available to allow the user to sync all patches and seals from a given mirror to either existing or alternative directories. Three arguments are required; the from which to sync, the existing or alternative output patches directory , and the existing or alternative seals directory . ./v.pl se http://thebitcoin.foundation patches2 seals2 Full vpatch sync complete to "patches2" Seal sync complete to "seals2" [ a | ante | antecedents ]: Arguments: () The a or ante or antecedents command is available to allow the user to view the antecedents of a given vpatch. One argument is required, the name of a . Example: ./v.pl a mod6_fix_dumpblock_params.vpatch Antecedent: asciilifeform_and_now_we_have_block_dumper_corrected.vpatch \ (asciilifeform, mod6) [ a/bitcoin/src/bitcoinrpc.cpp ] Example case, examine the antecedents of a given vpatch from an alternative directory: ./v.pl a asciilifeform_zap_showmyip_crud.vpatch pd patches2 Antecedent: asciilifeform_zap_hardcoded_seeds.vpatch (asciilifeform, mod6) \ [ a/bitcoin/src/net.cpp ] [ d | desc | descendants ]: Arguments: () The d or desc or descendants command is available to allow the user to view the descendants of a given . One argument is required, the name of a . Example: ./v.pl d mod6_fix_dumpblock_params.vpatch Descendant: asciilifeform_and_now_we_have_eatblock.vpatch \ (asciilifeform, mod6) [ a/bitcoin/src/bitcoinrpc.cpp ] Example case, examine the descendants of a given vpatch from an alternative directory: ./v.pl d asciilifeform_zap_showmyip_crud.vpatch pd patches2 Descendant: asciilifeform_dns_thermonyukyoolar_kleansing.vpatch \ (asciilifeform, mod6) [ a/bitcoin/src/net.cpp ] [ g | graph ]: Arguments & Options: ( []) The g or graph command is available to produce a topoligical flow graph in SVG format. The command has a required argument, the . The output Dot language file can be used to generate the SVG HTML output file with the `dot` binary. To produce the output Dot language file, the perl library Graph::Easy must be installed on the local environment. The optional command is given as a name for the . If 'graphviz' is installed on the local environment, then the `dot` binary should be available for V to invoke and generate the SVG HTML output for the user automatically. If it is not possible for the user to install 'graphviz' on the local environment for whatever reason, the Dot language output file can be copied to a seperate environment where 'graphviz' can be installed. A command like this is used to generate the SVG HTML output with the `dot` binary: `dot -Tsvg v-graph.dot > v-graph.html`. Example: ./v.pl g vpatch.dot vpatch-graph.html Printed Graphviz dot file to vpatch.dot Executed `dot` and built svg html output file: vpatch-graph.html Example case, build a graph from an alternative WoT, Patches and Seals directory: ./v.pl g vpatch-graph2.dot vpatch-graph2.html wd wot2 pd patches2 sd seals2 Printed Graphviz dot file to vpatch-graph2.dot Executed `dot` and built svg html output file: vpatch-graph2.html [ v | version ]: The v or version command simply prints the current version of V to stdout. This command takes no options or arguments. [ h | ? | help ]: The h or ? or help command will print a longer, more verbose help message to stdout. This command takes no options or arguments.