Converge sources configuration from a number of different places:
+
+
Command-Line Flags
+
+
Command-line flags will always be considered over any other source. To view
+them, send --help to any command. In addition, all commands have these flags:
+
+
+
--config: set the config file (see below for more info on this file)
+
--log-level: log level, one of TRACE, DEBUG, INFO, WARN, ERROR, or
+FATAL (INFO is used by default)
+
--nocolor: set to force colorless output
+
+
+
Environment
+
+
Environment variables are the same names as command-line flags, but prefixed by
+CONVERGE_ and with dashes replaced with underscores. For example, the
+--log-level flag can be set by setting the CONVERGE_LOG_LEVEL environment
+variable.
+
+
Config Files
+
+
Converge will source a single config file as a fallback. This config file can
+JSON, TOML, YAML, HCL, or a Java properties file (this is detected by file
+extension.) The keys of this file are the same as the command-line flags.
+Converge looks in /etc/converge/config.{ext} by default, but you can change
+this with the global --config flag.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/dependencies/index.html b/docs/dependencies/index.html
index 8b7ba29a0..c5b4f94fd 100644
--- a/docs/dependencies/index.html
+++ b/docs/dependencies/index.html
@@ -248,6 +248,32 @@
+
+
+
+
+
+
+
+ Server
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration
+
+
+
+
+
diff --git a/docs/getting-started/index.html b/docs/getting-started/index.html
index 3d2958c8d..b0fa0d2e9 100644
--- a/docs/getting-started/index.html
+++ b/docs/getting-started/index.html
@@ -248,6 +248,32 @@
+
+
+
+
+
+
+
+ Server
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration
+
+
+
+
+
diff --git a/docs/index.html b/docs/index.html
index d657d6fae..f1b82b228 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -248,6 +248,32 @@
+
+
+
+
+
+
+
+ Server
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration
+
+
+
+
+
diff --git a/docs/index.xml b/docs/index.xml
index 2983780ef..d86cc9bc8 100644
--- a/docs/index.xml
+++ b/docs/index.xml
@@ -6,13 +6,13 @@
Recent content on ConvergeHugo -- gohugo.ioen-us
- Thu, 25 Aug 2016 12:19:27 -0400
+ Tue, 30 Aug 2016 15:12:06 -0500docker.image
http://converge.aster.is/resources/docker-image/
- Thu, 25 Aug 2016 12:19:27 -0400
+ Tue, 30 Aug 2016 15:12:06 -0500http://converge.aster.is/resources/docker-image/
@@ -56,10 +56,170 @@ Valid time units are “ns”, “us” (or &
+
+ file.content
+ http://converge.aster.is/resources/file-content/
+ Tue, 30 Aug 2016 15:12:06 -0500
+
+ http://converge.aster.is/resources/file-content/
+
+
+<p>Content renders content to disk</p>
+
+<h2 id="example">Example</h2>
+
+<pre><code class="language-hcl">param "message" {
+ default = "Hello, World"
+}
+
+param "filename" {
+ default = "test.txt"
+}
+
+file.content "render" {
+ destination = "{{param `filename`}}"
+ content = "{{param `message`}}"
+}
+
+</code></pre>
+
+<h2 id="parameters">Parameters</h2>
+
+<ul>
+<li><code>content</code> (string)</li>
+</ul>
+
+<p>Content is the file content. This will be rendered as a template.</p>
+
+<ul>
+<li><code>destination</code> (string)</li>
+</ul>
+
+<p>Destination is the location on disk where the content will be rendered.</p>
+
+
+
+
+ file.mode
+ http://converge.aster.is/resources/file-mode/
+ Tue, 30 Aug 2016 15:12:06 -0500
+
+ http://converge.aster.is/resources/file-mode/
+
+
+<p>Mode monitors the mode of a file</p>
+
+<h2 id="example">Example</h2>
+
+<pre><code class="language-hcl">param "filename" {
+ default = "test.txt"
+}
+
+file.mode "render" {
+ destination = "{{param `filename`}}"
+ mode = 0777
+}
+
+</code></pre>
+
+<h2 id="parameters">Parameters</h2>
+
+<ul>
+<li><code>destination</code> (string)</li>
+</ul>
+
+<p>Destination specifies which file will be modified by this resource. The
+file must exist on the system (for example, having been created with
+<code>file.content</code>.)</p>
+
+<ul>
+<li><code>mode</code> (octal string)</li>
+</ul>
+
+<p>Mode is the mode of the file, specified in octal.</p>
+
+
+
+
+ module
+ http://converge.aster.is/resources/module/
+ Tue, 30 Aug 2016 15:12:06 -0500
+
+ http://converge.aster.is/resources/module/
+
+
+<p>Module remotely sources other modules and adds them to the tree</p>
+
+<h2 id="example">Example</h2>
+
+<pre><code class="language-hcl">param "message" {
+ default = "Hello from another module!"
+}
+
+module "basic.hcl" "basic" {
+ params = {
+ message = "{{param `message`}}"
+ }
+}
+
+</code></pre>
+
+<h2 id="parameters">Parameters</h2>
+
+<ul>
+<li><code>params</code> (map of string to anything)</li>
+</ul>
+
+<p>Params is a map of strings to anything you’d like. It will be passed to
+the called module as the default values for the <code>param</code>s there.</p>
+
+
+
+
+ param
+ http://converge.aster.is/resources/param/
+ Tue, 30 Aug 2016 15:12:06 -0500
+
+ http://converge.aster.is/resources/param/
+
+
+<p>Param controls the flow of values through <code>module</code> calls. You can use the
+<code>{{param "name"}}</code> template call anywhere you need the value of a param
+inside the current module.</p>
+
+<h2 id="example">Example</h2>
+
+<pre><code class="language-hcl">param "message" {
+ default = "Hello, World!"
+}
+
+param "filename" {
+ default = "test.txt"
+}
+
+task "render" {
+ check = "cat {{param `filename`}} | tee /dev/stderr | grep -q '{{param `message`}}'"
+ apply = "echo '{{param `message`}}' > {{param `filename`}}"
+}
+
+</code></pre>
+
+<h2 id="parameters">Parameters</h2>
+
+<ul>
+<li><code>default</code> (optional string)</li>
+</ul>
+
+<p>Default is an optional field that provides a default value if none is
+provided to this parameter. If this field is not set, this param will be
+treated as required.</p>
+
+
+
task
http://converge.aster.is/resources/task/
- Thu, 25 Aug 2016 10:03:34 -0500
+ Tue, 30 Aug 2016 15:12:06 -0500http://converge.aster.is/resources/task/
@@ -146,6 +306,150 @@ suffix, such as “300ms”, “-1.5h” or &
+
+ Configuration
+ http://converge.aster.is/configuration/
+ Mon, 29 Aug 2016 16:51:52 -0500
+
+ http://converge.aster.is/configuration/
+
+
+<p>Converge sources configuration from a number of different places:</p>
+
+<h2 id="command-line-flags">Command-Line Flags</h2>
+
+<p>Command-line flags will always be considered over any other source. To view
+them, send <code>--help</code> to any command. In addition, all commands have these flags:</p>
+
+<ul>
+<li><code>--config</code>: set the config file (see below for more info on this file)</li>
+<li><code>--log-level</code>: log level, one of <code>TRACE</code>, <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, <code>ERROR</code>, or
+<code>FATAL</code> (<code>INFO</code> is used by default)</li>
+<li><code>--nocolor</code>: set to force colorless output</li>
+</ul>
+
+<h2 id="environment">Environment</h2>
+
+<p>Environment variables are the same names as command-line flags, but prefixed by
+<code>CONVERGE_</code> and with dashes replaced with underscores. For example, the
+<code>--log-level</code> flag can be set by setting the <code>CONVERGE_LOG_LEVEL</code> environment
+variable.</p>
+
+<h2 id="config-files">Config Files</h2>
+
+<p>Converge will source a single config file as a fallback. This config file can
+JSON, TOML, YAML, HCL, or a Java properties file (this is detected by file
+extension.) The keys of this file are the same as the command-line flags.
+Converge looks in <code>/etc/converge/config.{ext}</code> by default, but you can change
+this with the global <code>--config</code> flag.</p>
+
+
+
+
+ Server
+ http://converge.aster.is/server/
+ Mon, 29 Aug 2016 16:49:53 -0500
+
+ http://converge.aster.is/server/
+
+
+<p>Converge comes with a server that can:</p>
+
+<ul>
+<li>run <code>plan</code> and <code>apply</code> and stream the results (using
+<a href="http://www.grpc.io/">gRPC</a>)</li>
+<li>serve modules from a given root</li>
+<li>serve the Converge binary itself, for bootstrapping new systems inside your
+network</li>
+</ul>
+
+<h2 id="https">HTTPS</h2>
+
+<p>You can run the server over HTTPS. If you don’t have your own certificates, you
+can use <a href="https://github.com/square/certstrap">certstrap</a> to get some with the
+following commands:</p>
+
+<pre><code class="language-shell">$ certstrap init --common-name your-company
+$ certstrap request-cert --ip 127.0.0.1
+$ certstrap sign 127.0.0.1 --CA your-company
+</code></pre>
+
+<p>Of course, replace <code>your-company</code> and <code>127.0.0.1</code> with your company’s name and
+the your server’s IP address, respectively (but those defaults will work fine
+for trying it out locally.) The certificates will be placed in <code>out</code> in the
+directory you run the command from.</p>
+
+<p>Afterwards, reference these files like so:</p>
+
+<pre><code class="language-shell">converge server --cert-file out/127.0.0.1.crt \
+ --key-file out/127.0.0.1.crt \
+ --ca-file out/your-company.crt \
+ --use-ssl \
+ --rpc-token your-token
+</code></pre>
+
+<p>You’ll also need to pass the <code>--ca-file</code> flag to commands like <code>plan</code> and
+<code>apply</code>, in order to trust your new CA (or put it in the system roots.)</p>
+
+<h2 id="apis">APIs</h2>
+
+<p>Using the Converge command-line interface is good enough for most cases. If you
+want to integrate Converge into your system in novel ways, however, an API is
+available.</p>
+
+<h3 id="authentication">Authentication</h3>
+
+<p>Authentication happens with <a href="https://jwt.io/">JSON Web Tokens</a>. The only
+currently supported algorithm is HS512, and issued tokens must have a 30 second
+expiration. Tokens are set using the <code>--rpc-token</code> <a href="http://converge.aster.is/configuration/">configuration flag</a> to all subcommands that use the API.</p>
+
+<h3 id="http-2-0-and-grpc">HTTP/2.0 And gRPC</h3>
+
+<p>If you want to create your own client for Converge, you’ll probably want to use
+gRPC. You can get instructions for your chosen langauge in
+<a href="http://www.grpc.io/docs/">the gRPC docs</a>, and the protobuf file is
+<code>rpc/pb/root.proto</code> in the Converge source. If you’re using Go, the client
+implementations in <code>rpc/client.go</code> are your friends.</p>
+
+<p>When using the RPC interface, the JWT token should be sent in the request
+metadata’s <code>authorization</code> field with the prefix <code>BEARER</code>.</p>
+
+<h3 id="http-1-1-and-json">HTTP/1.1 And JSON</h3>
+
+<p>A pseudo-RESTful interface is available to do the same things the gRPC interface
+can do. See the protobuf file for the most up-to-date endpoints and payload
+information.</p>
+
+<p>When using the HTTP/1.1 interface, the JWT token should be sent in the
+<code>Authorization</code> header with the prefix <code>BEARER</code>. You can also set the <code>jwt</code>
+querystring var, or send it in the <code>jwt</code> cookie.</p>
+
+<h2 id="standalone-server-for-the-command-line">Standalone Server For The Command-Line</h2>
+
+<p>The main Converge commands (like <code>plan</code> and <code>apply</code>) will take a <code>--local</code>
+argument (or set <code>CONVERGE_LOCAL=1</code>.) This will:</p>
+
+<ol>
+<li>Start a local RPC server</li>
+<li>Perform the requested action against the RPC server</li>
+<li>Shut down the RPC server</li>
+</ol>
+
+<p>During this process, a port (<code>localhost:26930</code>) will be opened and RPC will be
+running on it. This interface will be protected with an randomly-generated
+token, unless you specify <code>--no-token</code></p>
+
+<div class="admonition warning">
+<p class="admonition-title">Don't Disable Tokens</p>
+<p>Please don’t disable token generation with <code>--no-token</code>. I know we just said you
+can, but don’t do it. This will open up remote execution of arbitrary
+instructions to whoever can reach that port. You can make this process <em>more</em>
+secure by specifying <code>--cert-file</code>, <code>--key-file</code>, and optionally <code>--ca-file</code> to
+connect over HTTPS.</p>
+</div>
+
+
+
Module Organization
http://converge.aster.is/organization/
@@ -563,166 +867,6 @@ could
-
- param
- http://converge.aster.is/resources/param/
- Wed, 24 Aug 2016 23:45:18 -0500
-
- http://converge.aster.is/resources/param/
-
-
-<p>Param controls the flow of values through <code>module</code> calls. You can use the
-<code>{{param "name"}}</code> template call anywhere you need the value of a param
-inside the current module.</p>
-
-<h2 id="example">Example</h2>
-
-<pre><code class="language-hcl">param "message" {
- default = "Hello, World!"
-}
-
-param "filename" {
- default = "test.txt"
-}
-
-task "render" {
- check = "cat {{param `filename`}} | tee /dev/stderr | grep -q '{{param `message`}}'"
- apply = "echo '{{param `message`}}' > {{param `filename`}}"
-}
-
-</code></pre>
-
-<h2 id="parameters">Parameters</h2>
-
-<ul>
-<li><code>default</code> (optional string)</li>
-</ul>
-
-<p>Default is an optional field that provides a default value if none is
-provided to this parameter. If this field is not set, this param will be
-treated as required.</p>
-
-
-
-
- file.content
- http://converge.aster.is/resources/file-content/
- Wed, 24 Aug 2016 23:41:00 -0500
-
- http://converge.aster.is/resources/file-content/
-
-
-<p>Content renders content to disk</p>
-
-<h2 id="example">Example</h2>
-
-<pre><code class="language-hcl">param "message" {
- default = "Hello, World"
-}
-
-param "filename" {
- default = "test.txt"
-}
-
-file.content "render" {
- destination = "{{param `filename`}}"
- content = "{{param `message`}}"
-}
-
-</code></pre>
-
-<h2 id="parameters">Parameters</h2>
-
-<ul>
-<li><code>content</code> (string)</li>
-</ul>
-
-<p>Content is the file content. This will be rendered as a template.</p>
-
-<ul>
-<li><code>destination</code> (string)</li>
-</ul>
-
-<p>Destination is the location on disk where the content will be rendered.</p>
-
-
-
-
- module
- http://converge.aster.is/resources/module/
- Wed, 24 Aug 2016 23:41:00 -0500
-
- http://converge.aster.is/resources/module/
-
-
-<p>Module remotely sources other modules and adds them to the tree</p>
-
-<h2 id="example">Example</h2>
-
-<pre><code class="language-hcl">param "message" {
- default = "Hello from another module!"
-}
-
-module "basic.hcl" "basic" {
- params = {
- message = "{{param `message`}}"
- }
-}
-
-</code></pre>
-
-<h2 id="parameters">Parameters</h2>
-
-<ul>
-<li><code>params</code> (map of string to anything)</li>
-</ul>
-
-<p>Params is a map of strings to anything you’d like. It will be passed to
-the called module as the default values for the <code>param</code>s there.</p>
-
-
-
-
- file.mode
- http://converge.aster.is/resources/file-mode/
- Wed, 24 Aug 2016 23:29:09 -0500
-
- http://converge.aster.is/resources/file-mode/
-
-
-<p>Mode monitors the mode of a file</p>
-
-<h2 id="example">Example</h2>
-
-<pre><code class="language-hcl">param "filename" {
- default = "test.txt"
-}
-
-file.mode "render" {
- destination = "{{param `filename`}}"
- mode = 0777
-}
-
-</code></pre>
-
-<h2 id="parameters">Parameters</h2>
-
-<ul>
-<li><code>destination</code> (string)</li>
-</ul>
-
-<p>Destination specifies which file will be modified by this resource. The
-file must exist on the system (for example, having been created with
-<code>file.content</code>.)</p>
-
-<ul>
-<li><code>mode</code> (octal string)</li>
-</ul>
-
-<p>Mode is the mode of the file, specified in octal.</p>
-
-
-
License
http://converge.aster.is/license/
diff --git a/docs/install/index.html b/docs/install/index.html
index 978e1f463..54a935295 100644
--- a/docs/install/index.html
+++ b/docs/install/index.html
@@ -248,6 +248,32 @@
+
+
+
+
+
+
+
+ Server
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration
+
+
+
+
+
@@ -444,14 +470,14 @@
diff --git a/docs/resources/index.html b/docs/resources/index.html
index 77d29c57f..f5af75324 100644
--- a/docs/resources/index.html
+++ b/docs/resources/index.html
@@ -245,6 +245,32 @@
+
+
+
+
+
+
+
+ Server
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration
+
+
+
+
+
diff --git a/docs/resources/index.xml b/docs/resources/index.xml
index ebbe4179e..3b546e415 100644
--- a/docs/resources/index.xml
+++ b/docs/resources/index.xml
@@ -6,13 +6,13 @@
Recent content in Resources on ConvergeHugo -- gohugo.ioen-us
- Thu, 25 Aug 2016 12:19:27 -0400
+ Tue, 30 Aug 2016 15:12:06 -0500docker.image
http://converge.aster.is/resources/docker-image/
- Thu, 25 Aug 2016 12:19:27 -0400
+ Tue, 30 Aug 2016 15:12:06 -0500http://converge.aster.is/resources/docker-image/
@@ -57,29 +57,28 @@ Valid time units are “ns”, “us” (or &
- task
- http://converge.aster.is/resources/task/
- Thu, 25 Aug 2016 10:03:34 -0500
+ file.content
+ http://converge.aster.is/resources/file-content/
+ Tue, 30 Aug 2016 15:12:06 -0500
- http://converge.aster.is/resources/task/
+ http://converge.aster.is/resources/file-content/
-<p>Task allows you to run arbitrary shell commands on your system, first
-checking if the command should be run.</p>
+<p>Content renders content to disk</p>
<h2 id="example">Example</h2>
<pre><code class="language-hcl">param "message" {
- default = "Hello, World!"
+ default = "Hello, World"
}
param "filename" {
default = "test.txt"
}
-task "render" {
- check = "cat {{param `filename`}} | tee /dev/stderr | grep -q '{{param `message`}}'"
- apply = "echo '{{param `message`}}' > {{param `filename`}}"
+file.content "render" {
+ destination = "{{param `filename`}}"
+ content = "{{param `message`}}"
}
</code></pre>
@@ -87,69 +86,99 @@ task "render" {
<h2 id="parameters">Parameters</h2>
<ul>
-<li><code>interpreter</code> (string)</li>
+<li><code>content</code> (string)</li>
</ul>
-<p>the shell interpreter that will be used for your scripts. <code>/bin/sh</code> is
-used by default.</p>
+<p>Content is the file content. This will be rendered as a template.</p>
<ul>
-<li><code>check_flags</code> (list of strings)</li>
+<li><code>destination</code> (string)</li>
</ul>
-<p>flags to pass to the <code>interpreter</code> binary to check validity. For
-<code>/bin/sh</code> this is <code>-n</code></p>
+<p>Destination is the location on disk where the content will be rendered.</p>
+
+
+
+
+ file.mode
+ http://converge.aster.is/resources/file-mode/
+ Tue, 30 Aug 2016 15:12:06 -0500
+
+ http://converge.aster.is/resources/file-mode/
+
-<ul>
-<li><code>exec_flags</code> (list of strings)</li>
-</ul>
+<p>Mode monitors the mode of a file</p>
-<p>flags to pass to the interpreter at execution time</p>
+<h2 id="example">Example</h2>
-<ul>
-<li><code>check</code> (string)</li>
-</ul>
+<pre><code class="language-hcl">param "filename" {
+ default = "test.txt"
+}
-<p>the script to run to check if a resource needs to be changed. It should
-exit with exit code 0 if the resource does not need to be changed, and
-1 (or above) otherwise.</p>
+file.mode "render" {
+ destination = "{{param `filename`}}"
+ mode = 0777
+}
-<ul>
-<li><code>apply</code> (string)</li>
-</ul>
+</code></pre>
-<p>the script to run to apply the resource. Normal shell exit code
-expectations apply (that is, exit code 0 for success, 1 or above for
-failure.)</p>
+<h2 id="parameters">Parameters</h2>
<ul>
-<li><code>timeout</code> (duration string)</li>
+<li><code>destination</code> (string)</li>
</ul>
-<p>the amount of time the command will wait before halting forcefully. The
-format is Go’s duraction string. A duration string is a possibly signed
-sequence of decimal numbers, each with optional fraction and a unit
-suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”,
-“us” (or “µs”), “ms”, “s”, “m”, “h”.</p>
+<p>Destination specifies which file will be modified by this resource. The
+file must exist on the system (for example, having been created with
+<code>file.content</code>.)</p>
<ul>
-<li><code>dir</code> (string)</li>
+<li><code>mode</code> (octal string)</li>
</ul>
-<p>the working directory this command should be run in</p>
+<p>Mode is the mode of the file, specified in octal.</p>
+
+
+
+
+ module
+ http://converge.aster.is/resources/module/
+ Tue, 30 Aug 2016 15:12:06 -0500
+
+ http://converge.aster.is/resources/module/
+
+
+<p>Module remotely sources other modules and adds them to the tree</p>
+
+<h2 id="example">Example</h2>
+
+<pre><code class="language-hcl">param "message" {
+ default = "Hello from another module!"
+}
+
+module "basic.hcl" "basic" {
+ params = {
+ message = "{{param `message`}}"
+ }
+}
+
+</code></pre>
+
+<h2 id="parameters">Parameters</h2>
<ul>
-<li><code>env</code> (map of string to string)</li>
+<li><code>params</code> (map of string to anything)</li>
</ul>
-<p>any environment variables that should be passed to the command</p>
+<p>Params is a map of strings to anything you’d like. It will be passed to
+the called module as the default values for the <code>param</code>s there.</p>
param
http://converge.aster.is/resources/param/
- Wed, 24 Aug 2016 23:45:18 -0500
+ Tue, 30 Aug 2016 15:12:06 -0500http://converge.aster.is/resources/param/
@@ -188,28 +217,29 @@ treated as required.</p>
- file.content
- http://converge.aster.is/resources/file-content/
- Wed, 24 Aug 2016 23:41:00 -0500
+ task
+ http://converge.aster.is/resources/task/
+ Tue, 30 Aug 2016 15:12:06 -0500
- http://converge.aster.is/resources/file-content/
+ http://converge.aster.is/resources/task/
-<p>Content renders content to disk</p>
+<p>Task allows you to run arbitrary shell commands on your system, first
+checking if the command should be run.</p>
<h2 id="example">Example</h2>
<pre><code class="language-hcl">param "message" {
- default = "Hello, World"
+ default = "Hello, World!"
}
param "filename" {
default = "test.txt"
}
-file.content "render" {
- destination = "{{param `filename`}}"
- content = "{{param `message`}}"
+task "render" {
+ check = "cat {{param `filename`}} | tee /dev/stderr | grep -q '{{param `message`}}'"
+ apply = "echo '{{param `message`}}' > {{param `filename`}}"
}
</code></pre>
@@ -217,92 +247,62 @@ file.content "render" {
<h2 id="parameters">Parameters</h2>
<ul>
-<li><code>content</code> (string)</li>
+<li><code>interpreter</code> (string)</li>
</ul>
-<p>Content is the file content. This will be rendered as a template.</p>
+<p>the shell interpreter that will be used for your scripts. <code>/bin/sh</code> is
+used by default.</p>
<ul>
-<li><code>destination</code> (string)</li>
+<li><code>check_flags</code> (list of strings)</li>
</ul>
-<p>Destination is the location on disk where the content will be rendered.</p>
-
-
-
-
- module
- http://converge.aster.is/resources/module/
- Wed, 24 Aug 2016 23:41:00 -0500
-
- http://converge.aster.is/resources/module/
-
-
-<p>Module remotely sources other modules and adds them to the tree</p>
-
-<h2 id="example">Example</h2>
-
-<pre><code class="language-hcl">param "message" {
- default = "Hello from another module!"
-}
-
-module "basic.hcl" "basic" {
- params = {
- message = "{{param `message`}}"
- }
-}
-
-</code></pre>
-
-<h2 id="parameters">Parameters</h2>
+<p>flags to pass to the <code>interpreter</code> binary to check validity. For
+<code>/bin/sh</code> this is <code>-n</code></p>
<ul>
-<li><code>params</code> (map of string to anything)</li>
+<li><code>exec_flags</code> (list of strings)</li>
</ul>
-<p>Params is a map of strings to anything you’d like. It will be passed to
-the called module as the default values for the <code>param</code>s there.</p>
-
-
-
-
- file.mode
- http://converge.aster.is/resources/file-mode/
- Wed, 24 Aug 2016 23:29:09 -0500
-
- http://converge.aster.is/resources/file-mode/
-
+<p>flags to pass to the interpreter at execution time</p>
-<p>Mode monitors the mode of a file</p>
+<ul>
+<li><code>check</code> (string)</li>
+</ul>
-<h2 id="example">Example</h2>
+<p>the script to run to check if a resource needs to be changed. It should
+exit with exit code 0 if the resource does not need to be changed, and
+1 (or above) otherwise.</p>
-<pre><code class="language-hcl">param "filename" {
- default = "test.txt"
-}
+<ul>
+<li><code>apply</code> (string)</li>
+</ul>
-file.mode "render" {
- destination = "{{param `filename`}}"
- mode = 0777
-}
+<p>the script to run to apply the resource. Normal shell exit code
+expectations apply (that is, exit code 0 for success, 1 or above for
+failure.)</p>
-</code></pre>
+<ul>
+<li><code>timeout</code> (duration string)</li>
+</ul>
-<h2 id="parameters">Parameters</h2>
+<p>the amount of time the command will wait before halting forcefully. The
+format is Go’s duraction string. A duration string is a possibly signed
+sequence of decimal numbers, each with optional fraction and a unit
+suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”,
+“us” (or “µs”), “ms”, “s”, “m”, “h”.</p>
<ul>
-<li><code>destination</code> (string)</li>
+<li><code>dir</code> (string)</li>
</ul>
-<p>Destination specifies which file will be modified by this resource. The
-file must exist on the system (for example, having been created with
-<code>file.content</code>.)</p>
+<p>the working directory this command should be run in</p>
<ul>
-<li><code>mode</code> (octal string)</li>
+<li><code>env</code> (map of string to string)</li>
</ul>
-<p>Mode is the mode of the file, specified in octal.</p>
+<p>any environment variables that should be passed to the command</p>
diff --git a/docs/resources/module/index.html b/docs/resources/module/index.html
index b20032d4b..c68cdf6ee 100644
--- a/docs/resources/module/index.html
+++ b/docs/resources/module/index.html
@@ -245,6 +245,32 @@
+
+
+
+
+
+
+
+ Server
+
+
+
+
+
+
+
+
+
+
+
+
+ Configuration
+
+
+
+
+
@@ -449,7 +475,7 @@
Of course, replace your-company and 127.0.0.1 with your company’s name and
+the your server’s IP address, respectively (but those defaults will work fine
+for trying it out locally.) The certificates will be placed in out in the
+directory you run the command from.
You’ll also need to pass the --ca-file flag to commands like plan and
+apply, in order to trust your new CA (or put it in the system roots.)
+
+
APIs
+
+
Using the Converge command-line interface is good enough for most cases. If you
+want to integrate Converge into your system in novel ways, however, an API is
+available.
+
+
Authentication
+
+
Authentication happens with JSON Web Tokens. The only
+currently supported algorithm is HS512, and issued tokens must have a 30 second
+expiration. Tokens are set using the --rpc-tokenconfiguration flag to all subcommands that use the API.
+
+
HTTP/2.0 And gRPC
+
+
If you want to create your own client for Converge, you’ll probably want to use
+gRPC. You can get instructions for your chosen langauge in
+the gRPC docs, and the protobuf file is
+rpc/pb/root.proto in the Converge source. If you’re using Go, the client
+implementations in rpc/client.go are your friends.
+
+
When using the RPC interface, the JWT token should be sent in the request
+metadata’s authorization field with the prefix BEARER.
+
+
HTTP/1.1 And JSON
+
+
A pseudo-RESTful interface is available to do the same things the gRPC interface
+can do. See the protobuf file for the most up-to-date endpoints and payload
+information.
+
+
When using the HTTP/1.1 interface, the JWT token should be sent in the
+Authorization header with the prefix BEARER. You can also set the jwt
+querystring var, or send it in the jwt cookie.
+
+
Standalone Server For The Command-Line
+
+
The main Converge commands (like plan and apply) will take a --local
+argument (or set CONVERGE_LOCAL=1.) This will:
+
+
+
Start a local RPC server
+
Perform the requested action against the RPC server
+
Shut down the RPC server
+
+
+
During this process, a port (localhost:26930) will be opened and RPC will be
+running on it. This interface will be protected with an randomly-generated
+token, unless you specify --no-token
+
+
+
Don't Disable Tokens
+
Please don’t disable token generation with --no-token. I know we just said you
+can, but don’t do it. This will open up remote execution of arbitrary
+instructions to whoever can reach that port. You can make this process more
+secure by specifying --cert-file, --key-file, and optionally --ca-file to
+connect over HTTPS.