docs/func.pod

   1 =head1 NAME
   2
   3 Func -- Fedora Unified Network Controller.
   4
   5 =head1 SYNOPSIS
   6
   7 func "*" list_minions
   8
   9 func target.example.org call module method [args ...]
  10
  11 func "target*.example.org" call module method [args ...]
  12
  13 func "webserver1;mailserver2" call module method [args ...]
  14
  15 =head1 DESCRIPTION
  16
  17 "func" allows remote control of machines running funcd (called "minions")
  18 that are set to obey this machine (called the "overlord").  This includes
  19 performing various remote operations and gathering data.
  20
  21 "func" can address multiple machines at the same time by specifying
  22 their names with globs, which follow shell glob syntax.
  23
  24 See the project homepage (below) for a list of modules available
  25 and a more in-depth description of what each of them do.
  26
  27 =head1 THE "CALL" MODULE
  28
  29 The "call" module is used for running func modules remotely.
  30
  31 Format:  func "*.example.org" call <module> <function> [ args ... ]
  32
  33 =head1 LISTING REMOTE MODULES AVAILABLE
  34
  35 It's possible to ask func minions what modules they have installed:
  36
  37 func "*.example.org" call system list_modules
  38
  39 =head1 LISTING REMOTE FUNCTIONS AVAILABLE IN A MODULE
  40
  41 It is also possible to ask remote func modules what functions they support:
  42
  43 func target.example.org call modulename list_methods
  44
  45 =head1 CALLING A REMOTE COMMAND
  46
  47 Once you have the name of a module you want to run, use call to invoke it:
  48
  49 func target.example.org call modulename methodname
  50
  51 =head1 OUTPUT FORMATS
  52
  53 The "call" command by default outputs data using a "pretty printer".  Other
  54 display options include --raw, --json, and --xmlrpc, which may be more
  55 desirable if you are running func inside another script or prefer to read
  56 those display formats.
  57
  58 Example: func "*" call --json service inventory
  59
  60
  61 =head1 HELPER MODULES
  62
  63 In addition to "call", there are other modules that make control of remote
  64 machines, as well as data display, more user friendly.  They augment "call"
  65 by providing some additional functionality.
  66
  67 You will notice that the syntax for using one of these helper modules
  68 varies slightly from just using "call" directly.
  69
  70 For example "show" can be used to show remote data.  The normal command "func '*'
  71 command would dump a very large amount of data, while the show command can mine
  72 only a few details.  This might make things more readable, for instance, when
  73 not going through the Python API (where you would not care).
  74
  75 func "*.example.org" show hardware --help
  76
  77 func "*.example.org" show hardware systemMemory
  78
  79 func "*.example.org" show hardware os
  80
  81 Another useful helper command module is copyfile, which allows func to work like scp from
  82 the shell, though it can address multiple systems at the same time.
  83
  84 The following example pushes one file out to multiple systems:
  85
  86 func "*.example.org" copyfile --file=/tmp/foo --remotepath=/tmp/foo
  87
  88 While these helper modules will grow over time, usage of "call" syntax
  89 directly is fine also.  See the Wiki for more examples as they evolve.
  90
  91 =head1 --verbose
  92
  93 Use this flag to output extra information from func while it is running.
  94 All func commands can take this flag.
  95
  96 =head1 EXIT_STATUS
  97
  98 Func commands have return values that vary based on the module being
  99 called.  See the project page (linked below) for more information.
 100
 101 =head1 ADDITONAL RESOURCES
 102
 103 See https://hosted.fedoraproject.org/projects/func/ for more information, including information on scripting func from Python.
 104
 105 See also the manpages for "func-inventory", "funcd", "certmaster", and "certmaster-ca".
 106
 107 =head1 AUTHOR
 108
 109 Various. See https://hosted.fedoraproject.org/projects/func
 110
 111