feat: Initial release (#1)

orbiously · Sep 21, 2022 · 147fea2 · 147fea2
1 parent ccb30b1
commit 147fea2
Show file tree

Hide file tree

Showing 24 changed files with 599 additions and 94 deletions.
diff --git a/.circleci/test-deploy.yml b/.circleci/test-deploy.yml
@@ -2,6 +2,7 @@ version: 2.1
 orbs:
   zerotier: orbiously/zerotier@dev:<<pipeline.git.revision>>
   orb-tools: circleci/orb-tools@11.1
+  win: circleci/windows@5.0.0
 
 filters: &filters
   tags:
@@ -10,18 +11,66 @@ filters: &filters
 jobs:
   # Create a job to test the commands of your orbs.
   # You may want to add additional validation steps to ensure the commands are working as expected.
-  command-tests:
-    docker:
-      - image: cimg/base:current
+  # command-tests-docker:
+  #   docker:
+  #     - image: cimg/base:2022.08
+  #   resource_class: small
+  #   steps:
+  #     - zerotier/connect:
+  #         zerotier-remote-member: "10.244.72.250"
+  #     - zerotier/disconnect
+  command-tests-linux:
+    machine:
+      image: ubuntu-2004:202201-02
+    resource_class: medium
     steps:
-      - checkout
-      # Run your orb's commands to validate them.
-      - zerotier/greet
+      - zerotier/connect:
+          zerotier-remote-member: "10.244.72.250"
+      - run:
+          name: Check apparent public IP
+          command: |
+            curl -s checkip.amazonaws.com
+            curl -s ifconfig.co
+      - zerotier/disconnect
+  command-tests-macos:
+    macos:
+      xcode: "14.0.0"
+    steps:
+      - zerotier/connect:
+          zerotier-remote-member: "10.244.72.250"
+          full-vpn: true
+      - run:
+          name: Check apparent public IP
+          command: |
+            curl -s checkip.amazonaws.com
+            curl -s ifconfig.co
+      - zerotier/disconnect:
+          store-settings-dump: true
+  command-tests-windows:
+    executor:
+      name: win/default
+    steps:
+      - run: choco install zerotier-one -y
+      - zerotier/connect:
+          zerotier-remote-member: "10.244.72.250"
+      - run:
+          shell: bash
+          name: Check apparent public IP
+          command: |
+            curl -s checkip.amazonaws.com
+            curl -s ifconfig.co
+      - zerotier/disconnect
 workflows:
   test-deploy:
     jobs:
       # Make sure to include "filters: *filters" in every test job you want to run as part of your deployment.
-      - command-tests:
+      - command-tests-linux:
+          filters: *filters
+      # - command-tests-docker:
+      #     filters: *filters
+      - command-tests-macos:
+          filters: *filters
+      - command-tests-windows:
           filters: *filters
       - orb-tools/pack:
           filters: *filters
@@ -31,7 +80,11 @@ workflows:
           pub-type: production
           requires:
             - orb-tools/pack
-            - command-tests
+            - command-tests-linux
+            # - command-tests-docker
+            - command-tests-macos
+            - command-tests-windows
+
           context: orb-publishing
           filters:
             branches:

diff --git a/README.md b/README.md
@@ -1,39 +1,96 @@
-# Orb Template
+# ZeroTier Orb
 
 
 [![CircleCI Build Status](https://circleci.com/gh/orbiously/zerotier-orb.svg?style=shield "CircleCI Build Status")](https://circleci.com/gh/orbiously/zerotier-orb) [![CircleCI Orb Version](https://badges.circleci.com/orbs/orbiously/zerotier.svg)](https://circleci.com/orbs/registry/orb/orbiously/zerotier) [![GitHub License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://raw.githubusercontent.com/orbiously/zerotier-orb/master/LICENSE) [![CircleCI Community](https://img.shields.io/badge/community-CircleCI%20Discuss-343434.svg)](https://discuss.circleci.com/c/ecosystem/orbs)
 
 
 
-A project template for Orbs.
+This orb will allow you to connect the build-host to a ZeroTier network, communicate with any other member of the ZeroTier network, and alternatively use another ZeroTier member as a jump/bastion host.
 
-This repository is designed to be automatically ingested and modified by the CircleCI CLI's `orb init` command.
+_Note that even if you choose to route **all** Internet via the ZeroTier member acting as a jump/bastion host (`full-vpn: true`), traffic between the build-agent and other CircleCI components/services, as well as, DNS requests **will not** be routed through the ZeroTier network._
 
-_**Edit this area to include a custom title and description.**_
+**This is an “executor-agnostic” orb; there is only one set of commands which can be used on any _supported_ executor. The orb’s underlying code handles the OS/platform detection, and runs the appropriate OS-specific bash commands.**
 
 ---
 
+## Executor support
+
+| Linux (`machine`)  | Windows | macOS  | Docker |
+| :---: | :---: | :---: | :---: |
+| :white_check_mark:  | :white_check_mark:  | :white_check_mark:  | :x:  |
+
+
+## Requirements
+
+Before attempting to use this ZeroTier orb:
+
+- You should have access to a ZeroTier network with at least **one online** member/node.
+
+    - The ZeroTier IP address must be referenced via the `zerotier-remote-member` parameter of the orb's connect command.
+
+- Ensure you have stored the ZeroTier network ID **and** a ZeroTier [API access token](https://my.zerotier.com/account) in respective environment variables  (either in the [project settings](https://circleci.com/docs/env-vars#setting-an-environment-variable-in-a-project) or in an [organization context](https://circleci.com/docs/env-vars#setting-an-environment-variable-in-a-context)).
+
+    - By default, the orb's `connect` command expects the ZeroTier netword ID and the ZeroTier API access token to be stored in environment variables respectively named `ZT_NET_ID` and `ZT_API_TOKEN`, however you can opt to store them in custom-named environment variables; in such case, the environment variables' names **must be** passed to the orb's `connect` command via the `net-id-var` and `api-token-var` parameters.
+
+- If you want to route traffic to specific IPs via the Zerotier member specified in the `zerotier-remote-member` parameter, you'll need the [appropriate managed route](https://zerotier.atlassian.net/wiki/spaces/SD/pages/224395274/Route+between+ZeroTier+and+Physical+Networks).
+
+- If you want to route **all Internet traffic** via the Zerotier member specified in the `zerotier-remote-member` parameter, make sure you've added a [(managed) default route](https://zerotier.atlassian.net/wiki/spaces/SD/pages/7110693/Overriding+Default+Route+Full+Tunnel+Mode).
+
+
+## Features
+
+This orb has 2 commands:
+- `connect`
+- `disconnect`
+
+There are **no job or executor** defined in this orb.
+
+
+### Commands
+
+The `connect` command will:
+- Download/Install ZeroTier (if needed).
+- Start the ZeroTier service (if needed).
+- Make the build-host join the specified ZeroTier network.
+- Authorize the member via a request to the ZeroTier API.
+- [**Only if you use `full-vpn: true`**] Add CircleCI-specific routes to prevent traffic between the build-agent and other CircleCI components/services, as well as, DNS requests from being routed through the ZeroTier network.
+
+The `disconnect` command will:
+- Make the build-host leave the ZeroTier network.
+- Stop the ZeroTier service.
+- [**Only if you use `store-log: true`**] Generate a debug settings dump and store it as an artifact.
+
+
+## Caveats & limitations
+
+- The orb adds route to prevent traffic between the build-agent and other CircleCI components/services, as well as, DNS requests from being routed through the ZeroTier network.
+
+  This is necessary to avoid networking issues when you routing all Internet traffic through the ZeroTier network.
+
+  **However, these routes are based on the current architecture of the CircleCI build-environement, which is subject to change over time thus rendering the aforementioned routes exclusions obsolete and ineffective.**
+
+- When choosing your ZeroTier network IP range, make sure it doesn't conflict with the build-host's existing network/routing configuration.
+
+- The `docker` executor is not supported (due to [limitations of unprivileged LXC containers](https://circleci.com/blog/vpns-and-why-they-don-t-work/) used in CircleCI).
+
+
 ## Resources
 
 [CircleCI Orb Registry Page](https://circleci.com/orbs/registry/orb/orbiously/zerotier) - The official registry page of this orb for all versions, executors, commands, and jobs described.
 
 [CircleCI Orb Docs](https://circleci.com/docs/2.0/orb-intro/#section=configuration) - Docs for using, creating, and publishing CircleCI Orbs.
 
-### How to Contribute
-
-We welcome [issues](https://github.com/orbiously/zerotier-orb/issues) to and [pull requests](https://github.com/orbiously/zerotier-orb/pulls) against this repository!
-
-### How to Publish An Update
-1. Merge pull requests with desired changes to the main branch.
-    - For the best experience, squash-and-merge and use [Conventional Commit Messages](https://conventionalcommits.org/).
-2. Find the current version of the orb.
-    - You can run `circleci orb info orbiously/zerotier | grep "Latest"` to see the current version.
-3. Create a [new Release](https://github.com/orbiously/zerotier-orb/releases/new) on GitHub.
-    - Click "Choose a tag" and _create_ a new [semantically versioned](http://semver.org/) tag. (ex: v1.0.0)
-      - We will have an opportunity to change this before we publish if needed after the next step.
-4.  Click _"+ Auto-generate release notes"_.
-    - This will create a summary of all of the merged pull requests since the previous release.
-    - If you have used _[Conventional Commit Messages](https://conventionalcommits.org/)_ it will be easy to determine what types of changes were made, allowing you to ensure the correct version tag is being published.
-5. Now ensure the version tag selected is semantically accurate based on the changes included.
-6. Click _"Publish Release"_.
-    - This will push a new tag and trigger your publishing pipeline on CircleCI.
+## Important note regarding support
+
+This is an [**uncertified** orb](https://circleci.com/docs/orbs-faq#using-uncertified-orbs); it is **neither tested nor verified by CircleCI**. Therefore CircleCI **will not** be in a position to assist you with using this orb, or troubleshooting/resolving any issues you might encouter while using this orb.
+
+Should you have questions or encounter an issue while using this orb, please:
+
+1. Refer to the "[Caveats & limitations](https://github.com/orbiously/zerotier-orb/README.md#caveats--limitations)" section.
+2. Check if there is a similar [existing question/issue](https://github.com/orbiously/zerotier-orb/issues). If so, you can add details about your instance of the issue.
+3. Visit the [Orb category of the CircleCI Discuss community forum](https://discuss.circleci.com/c/orbs). 
+4. If none of the above helps, [open your own issue](https://github.com/orbiously/zerotier-orb/issues/new/choose) with a **detailled** description.
+
+## Contribute
+
+You are more than welcome to contribute to this orb by adding features/improvements or fixing open issues. To do so, please create [pull requests](https://github.com/orbiously/zerotier-orb/pulls) against this repository, and make sure to provide the requested information.
diff --git a/src/@orb.yml b/src/@orb.yml
@@ -1,15 +1,10 @@
 version: 2.1
 
 description: >
-  Sample orb description
-# What will your orb allow users to accomplish?
-# Descriptions should be short, simple, and informative.
+  Connect the build-host to your ZeroTier network and establish a link with another ZeroTier member.
+  If you've created managed routes in your ZeroTier network, you can use that remote ZeroTier member as a bastion/jump host.
 
 # This information will be displayed in the orb registry and is not mandatory.
 display:
-  home_url: "https://www.example.com/docs"
+  home_url: "https://www.zerotier.com"
   source_url: "https://github.com/orbiously/zerotier-orb"
-
-# If your orb requires other orbs, you can import them like this. Otherwise remove the "orbs" stanza.
-# orbs:
-#  hello: circleci/hello-build@0.0.5
diff --git a/src/commands/connect.yml b/src/commands/connect.yml
@@ -0,0 +1,51 @@
+description: |
+  This command installs ZeroTier (if needed), checks that all required environement variables are set.
+  Then it connects the build-host (ZeroTier member) to the specified ZeroTier network.
+
+parameters:
+  net-id-var:
+    type: env_var_name
+    default: ZT_NET_ID
+    description: |
+      Name of the nevironment variable containing the ZeroTier network ID.
+  api-token-var:
+    type: env_var_name
+    default: ZT_API_TOKEN
+    description: |
+      Name of the nevironment variable containing the ZeroTier API token.
+  zerotier-remote-member:
+    type: string
+    description: |
+      ZeroTier IP address of the ZeroTier remote member to establish a link with, and potentially use as a bastion/jump host.
+  full-vpn:
+    type: boolean
+    default: false
+    description: |
+      Whether or not to route all traffic through the ZeroTier network and ZeroTier remote member.
+      (Note: the full-vpn implementation is not recommended. See the "Caveats & limitations" section of the repository's README)
+
+
+steps:
+  - run:
+      environment:
+        PARAM_ZT_NET_ID: << parameters.net-id-var >>
+        PARAM_ZT_API_TOKEN: << parameters.api-token-var >>
+        SCRIPT_SETUP_LINUX: << include(scripts/linux/setup.sh) >>
+        SCRIPT_SETUP_WINDOWS: << include(scripts/windows/setup.sh) >>
+        SCRIPT_SETUP_MACOS: << include(scripts/macos/setup.sh) >>
+      name: Setting up ZeroTier
+      command: <<include(scripts/setup.sh)>>
+      shell: bash
+
+  - run:
+      environment:
+        PARAM_ZT_NET_ID: << parameters.net-id-var >>
+        PARAM_ZT_API_TOKEN: << parameters.api-token-var >>
+        PARAM_ZT_REMOTE_MBR: << parameters.zerotier-remote-member >>
+        PARAM_FULL_VPN: << parameters.full-vpn >>
+        SCRIPT_CONNECT_LINUX: << include(scripts/linux/connect.sh) >>
+        SCRIPT_CONNECT_WINDOWS: << include(scripts/windows/connect.sh) >>
+        SCRIPT_CONNECT_MACOS: << include(scripts/macos/connect.sh) >>
+      name: Connecting to ZeroTier Network
+      command: <<include(scripts/connect.sh)>>
+      shell: bash
diff --git a/src/commands/disconnect.yml b/src/commands/disconnect.yml
@@ -0,0 +1,29 @@
+description: |
+  This command disconnects the build-host from the ZeroTier network, stores the ZeroTier log (if option enabled), and finally stops the ZeroTier service.
+
+parameters:
+  store-settings-dump:
+    type: boolean
+    default: false
+    description: |
+      Whether or not to store the ZeroTier log file.
+      If set to `true`, a `zerotier.log` file will be available under the "Artifacts" tab.
+
+steps:
+  - run:
+      environment:
+        PARAM_STORE_DUMP: << parameters.store-settings-dump >>
+        SCRIPT_LEAVE_LINUX: << include(scripts/linux/disconnect.sh) >>
+        SCRIPT_LEAVE_WINDOWS: << include(scripts/windows/disconnect.sh) >>
+        SCRIPT_LEAVE_MACOS: << include(scripts/macos/disconnect.sh) >>
+      name: Disconnecting from ZeroTier network.
+      command: <<include(scripts/disconnect.sh)>>
+      shell: bash
+      when: always
+
+  - when:
+      condition: << parameters.store-settings-dump >>
+      steps:
+        - store_artifacts:
+            path: /tmp/zerotier_dump.txt
+            destination: zerotier.dump
diff --git a/src/commands/greet.yml b/src/commands/greet.yml
diff --git a/src/examples/example.yml b/src/examples/example.yml
diff --git a/src/examples/use-custom-envvars-and-store-settings-dump.yml b/src/examples/use-custom-envvars-and-store-settings-dump.yml
@@ -0,0 +1,38 @@
+description: >
+  Use your Zerotier network ID and ZeroTier API token stored in custom-named environment variables.
+  Store the ZeroTier log as artifact upon disconnection.
+
+usage:
+  version: 2.1
+  orbs:
+    zerotier: orbiously/zerotier@1.0.0
+    win: circleci/windows@5.0.0
+
+  jobs:
+    for-the-win:
+      executor:
+        name: win/default
+      steps:
+        - zerotier/connect:
+            net-id-var: MY_ZEROTIER_NETWORK
+            api-token-var: TOKEN_SAFE_PLACE
+            zerotier-remote-member: "10.244.72.250"
+        - run:
+            shell: bash
+            name: Check apparent public IP
+            command: |
+              curl -s ifconfig.co
+              # If you've added a managed route to the "ifconfig.co" hostname's IPs via the ZeroTier member with private IP "10.244.72.250"
+              # then the above command will return the public IP of that ZeroTier member.
+              # (https://zerotier.atlassian.net/wiki/spaces/SD/pages/224395274/Route+between+ZeroTier+and+Physical+Networks)
+        - run:
+            shell: bash
+            name: List other peers in this Zerotier network
+            command: |
+              /c/progra~2/ZeroTier/One/zerotier-cli.bat listpeers
+        - zerotier/disconnect:
+            store-log: true
+  workflows:
+    winning:
+      jobs:
+        - for-the-win