Repository files navigation

The command-line tool to wrangle your Tailscale tailnet cluster whether large or small.

Any Tailscale user whether a hobbyist with a 3 node cluster or a seasoned cloud professional managing thousands ofproduction nodes can benefit from this tool.tips is the go-to tool to quickly and effectively manage an ever growingtailnet cluster. It allows you to confidently slice | dice | filter nodes, remotely executecommands, and manage your nodes collectively using an effective pattern modeled after cloud automation software.

• 😎 - A richer experience when ran on a nodewithin the tailnet network
• 📝 - Nearly zero-config managed viaViper andCobra, with sane defaults
• ⚡️ - Caching and indexed viaBBolt key-value store for fast queries
• 🔎 - Powerful complex filtering expression, sorting, slicing and dicing built-in
• 👩‍💻‍ - Developer focused tooling
• ✅ - Remote command execution and ssh tooling built-in
• 🫦 - Beautifully rendered terminal output thanks toCharmbracelet's lipgloss
• 👍🏼 - No deployable dependencies, single binary thanks to theGo programming language

• Installation
• Definitions
• Why the name?
• How to Guide
• Built with ❤️
• F.A.Q.
• Alpha Status
• Disclaimer

First, grab thetips binary by doing a typical install from source:

$ go install github.com/deckarep/tips@latest

Next, log into your Tailscale account and create anAPI Access token.

1. Link to create API Access token
2. UnderAPI Access Tokens click:Generate access token...
3. Provide aDescription liketips-cli and choose an expiry time or keep the90 days default.
4. After clicking the Generate button copy the key that looks like:tskey-api-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx and save it in thetips config file.
5. Follow security best-practices by not sharing this key or copying it into a public repo!
6. tips uses this key to remotely access the Tailscale Web API.

At anabsolute minimumtips requires thetips_api_key and atailnet to be specified in order to use this app.Here is how you can set this up.

As an environment variable:

export TIPS_API_KEY=tskey-api-xxxxxxxxxxxx-xxx...export TAILNET=user@domain.com

Or, in the~/.tips.cfgJSON file placed in your homedir:

{"tips_api_key":"tskey-api-xxxxxxxxxxxx-xxx...","tailnet":"user@domain.com"}

Lastly, on-demand by using the relevant flags:

# This will get tedious and not recommended long term$ ./tips --tailnet user@domain.com --tips_api_key tskey-api-xxxxxxxxxxxx-xxx...

• Tailscale: makes creating software-defined networks easy: securely connecting users, services, and devices
• tailnet: a single private network built from one or more nodes using Tailscale
• tips (this tool): a command-line tool to easily manage a tailnet cluster for use on Mac, PC, or Linux

• Easily view your nodes in abeautifully rendered and consistent table view
• Viewenriched, realtime info such asonline status when ran from the context of a node within a tailnet
• Filter nodes based on:tags,OS,hostname and other fields
• Slice or segment nodes to work on a portion of them at a time
• Easilyssh into a node
• Executesingle-shot complex commands against all matching nodes in parallel with controllable concurrency
• Tail the logs of long-running sessions from multiple nodes
• Broadcast commands to multiple nodes using thecsshx power-tool if installed
• Quickly generate a, or\n delimited list of nodes for reporting or use in other apps/cli tools
• Quickly generate ajson list of nodes

...with automatic but configurable file-system caching built-in which means fast, consistent results everytime!

• The name must be short, this tool must not get in the way and will likely be often used to query infrastructure
• Simply put, this tool is about managing a (t)ailnet's distributed (ips) or nodes which shortens to:tips
• Lastly, what better way to show appreciation for software than toleave a tip especially if used in aprofessional or commercial setting?

Here is a list of common commands from easy to more advanced.

How do I use this command-line tool?

# Here is the general layout, how to use it as everything practically everything is optional by default../tips [optional-primary-devices-filter] [optional-remote-command] --flags param0, param1, --moreflags

How do I get a list ofalldevices ornodes in atailnet?

./tips./tips @# This is equivalent as @ means all/everything.

# Simply provide a partial or full string name../tips [prefix]./tips blade# Find all nodes with a machine name starting with 'blade'./tips bla# Find all nodes with a machine name starting with 'bla'# Multiple are supported too, but must be in quotes../tips"[prefix-0] | [prefix-1] ... | [prefix-n]"# Find all nodes starting with: 'foo' or 'bar' or 'baz'./tips"foo | bar | baz"# Lastly, you can also slice the result../tips"[prefix-0] | [prefix-1] ... | [prefix-n] [optional-slice]"# Does a prefix search on foo OR bar and returns the results from 5 to 10.# NOTE: when more than one prefix is provided, this acts as multiple indexed searches../tips"foo | bar [5:10]"

# Comma delimited filtering is an AND-type conditional: this returns all devices that match both linux AND user@foo.com./tips --filter'linux, user@foo.com'# Pipe delimited is an OR-type conditional: this returns all devices that match both linux OR user@foo.com./tips --filter'linux | user@foo.com'# Complex/nested filtering is supported with parentheses having precedence../tips --filter'(linux, (peanuts | walnuts), (user@foo.com | them@website.com))'# Glob-style filtering as prefix, suffix or a combination of both works too!./tips --filter'1.54*, *foo.com, *dog*'

# Not yet supported, need to think about what this even does.# ./tips --details

# Partially working (some fields not supported)# To sort by one column ascending (default)./tips --sort'name'# To sort by multiple columns with varying order, specifically in ascending or descending order./tips --sort'name:dsc,email:asc'

# Shows only the first 5 nodes./tips --slice'[0:5]'# Shows the nodes from 5 to 10./tips --slice'[5:10]'# Show nodes from 5 on up./tips --slice'[5:]'

How do I add/remove columns to be returned?

# List one or more columns to additionally include beyond the default# ./tips --columns 'ipv6, authorized'# By prefixing with a - (dash) you can exclude one or more columns# ./tips --columns '-ipv4, -user'# Or you can do a combination of include and exclude# ./tips --columns 'ipv6, -user'

How do I generate a JSON-based result

./tips --json

How do I generate a list of ips only

# Provides a \n delimited list of ips./tips --ips# Provides a comma delimited list of ips./tips --ips --delimiter','

How do run a remote command on all returned nodes?

./tips [prefix-filter] [remotecommand here]./tips blade"hostname"# runs the remote command 'hostname' on all nodes that start with prefix:blade./tips bla"echo 'hello'" -c20# same as above but does an echo with a concurrency value of 20.

How do I rebuild the index? Running this forces a full rebuild (fetch all remote data) and builds the indexfor speedy queries. Normally you don't have to do this manually.

# Not yet supported# ./tips --reindex

• MacOS (actively developed, tested)
• Linux (planned soon, untested, may work to some degree)
• PC (future planned, untested, contributions welcome)

• by deckarep

Q: I'm having trouble executing remote commands on some nodes in mytailnet.

A: This is typically not a problem with this tool, but rather yourtailnet configuration with respect topermissions ortagging orssh auth keys. Please check that your nodes have the appropriateports open,permissions and/orpublic keys to match your userlogon credentials.

Q: I'm having troublesshing into a node with this tool.

A: This tool does absolutely nothing special to manage ssh-based logins andsimply forwards such requests toeither theTailscale ssh subcommand or thenative ssh executable. Please see the previous question as for whatcould be wrong.

Q: I have a massive infrastructure. Will this tool help me manage a large infrastructure with 10's of thousands ofnodes?.

A: Yes, withrobust caching and indexing built-in, this tool ensures fast queries amongst even the largestclusters. One of the primary goals of this project is that it can help you manage atailnet from5 to 50,000nodes. It all boils down to the indexing/caching strategies, and it largely depends on query use cases.

Q: How can I execute remote commands with a greater degree ofparallelism orconcurrency?

A: We have you covered: see the-c or--concurrency flag.

Q: When executing remote commands how can I viewstderr as well asstdout?

A: Use the--stderr flag.

A: Use the--nocolor flag.

Q: How can I disable colored output?

A: See the--nocolor flag.

Q: Isn't caching with BBolt overkill?

A: Probably, but integration is easy and some users are expected to be managing thousands of nodes via Tailscale.

Q: But why u no have unit-tests?

A: Because this is a prototype! I am rapidly designing what I think this software should look like and in thisphase, unit-tests will slow me down. I've already gone through several major refactors and will likely have more comingup but this will change. Eventually the design will be nailed down and unit-testswill be a must!

This code is currently being developed in arapid prototyping mode. Therefore you will not see much unit-testing astoo much code is changing and being actively refactored as the design and approach is tightened up. If you use this atthis stage please understand that things are bound to change or be broken until I promote this software to being at the"beta" stage. Currently only MacOS builds are working.

Please note that this project is a personal and independent initiative. It is not endorsed, sponsored, affiliated with,or otherwise associated with any company or commercial entity. This project is developed and maintained by individualcontributors in their personal capacity. The views and opinions expressed here are those of the individual contributorsand do not reflect those of any company or professional organization they may be associated with.