Skip to content

BashPlus for Dyn

Jump to bottom
monstruooo edited this page May 16, 2017 · 24 revisions

Summary:

Getting started with bash+

You start by sourcing the file common.functions. This will source all other files that contain bash+ functions

Once you have the functions in your shell and you run the first DynDNS command (any command), you will be prompted for credentials. These are saved as variables inside your shell until you leave the current session

Listing/Searching/Creating domains

You can list all domains in your account with the command dyn ls

Now lets create a new domain. Notice the use of grep to filter domains. All standard bash tools are available to you in bash+

Creating records

Next, we populate the newly created domain with some records.

Creating a naked A record

Creating a cname

Created a naked text record and listing that record by its id to see all its values

Updating existing records

You can also update existing records, using the same command dyn record mk

Updating naked records is more tricky. You should incorporate the record id in your command. You do it using a special <id>/@ notation

You can use <record id>/<record name> notation to update normal records too. This would make your commands run faster when updating existing records

Listing/filtering domain records

You have four ways to list records:

  • dyn ls <domain> lists records but without values. Fast
  • dyn ls <domain> all lists all records with their values. Takes time.
  • dyn ls <domain> naked lists all naked records with values
  • dyn ls <domain> id1 id2 id3

Deleting domains/records

To delete records, run dyn rm <domain> <record1 id> <record2 id> ... Multiple records can be specified at the same time

To delete domain, run dyn domain rm <domain>. For example dyn domain rm oskar-test.com

This command asks for confirmation. In case you are running it in a script, use regular bash redirection to simulate user input

Custom API requests

The command dyn record mk above can process records of the type A, CNAME and TXT. It doesn’t work with MX or SRV records. However, you can take advantage of bash+ functions to easily create your own requests to the API.

Bash+ has function dyn_api to access API that can be also evoked as dyn api

dyn_api takes care of some aspects such as initiating and maintaining the authorization token. You only need to complete your request with relevant arguments to curl

So lets take as an example creating an MX record. From the online API manual:

HTTP Action POST means that your request should include -X POST switch

dyn api -X POST

You provide arguments with switch --data

dyn api -X POST --data <arguments>

API expects arguments in the json format. You can use bash+ args2json function to easily construct the json

For your MX record, args2json would look like this:

args2json rdata.preference=0 rdata.exchange=mail.oskar-test.com ttl=14400

And this is the json for API you receive from args2json:

{"rdata":{"preference":0,"exchange":"mail.oskar-test.com"},"ttl":14400}

In the screenshot below I first save the output of args2json to a variable and then use this variable in my command.

The last parameter to dyn_api is the url you send your request to

In the screenshot below it all comes together as we create the MX record.

Immediately after the record is created you run command dyn publish changes <domain>. Until you run this command, your configuration changes such as new/updated records are not applied

The format <command1 > && <command2> in bash means that command2 only runs if command1 finished successfully

Appendix A. Notes for scripters

Bash+ takes care of several aspects of accessing DynDNS:

  • Token management
  • Publishing changes

Basically whenever you use bash+ dyndns extensions, an authorization token is automatically requested and kept alive. Bash+ functions don’t delete the token after completing their requests. However, DynDNS considers it a good practice to close the token when the task is completed. In case you want to close the token, use dyn token kill command.

Sometimes you may want to run asynchronous requests to API with different tokens to avoid the rate limit (5 requests/second). In this case you would run your requests in subshells at the background. To cause bash+ to request a ticket for your subshell, localize variables dyn_token and dyn_token_ts after you start the subshell. New token will be then requested when you run dyn api inside the subshell. You can close the token with dyn token kill command at the end of the subshell. Here is an example from one of the bash+ functions

Another aspect to consider is the publishing of changes. Most API commands of DynDNS only submit their changes to the API without actually implementing them. You need to send a publish command to activate the new configuration. Keep in mind that if you delete the authorization token, all updates submitted using this token are lost. You need to publish your changes before you close the token

Bash+ has two commands dyn publish zone for newly created domains and dyn publish changes to publish new/updated records.

All commands that add/update domain/records that come with bash+ publish changes after every API request. In case you work with many records in the same domain, you may prefer to save on requests and first submit all your changes using dyn_api command and only then publish them.

The following error codes are returned by dyn api. You can use them to identify the source of error and also to know what kind of output is saved in res variable

  • 0 - Request succeeded
  • 1 - The API informed you that your request failed
  • 2 - The request failed and the response is not in json format (DynDNS responds to certain errors with html pages)
  • 10+ Curl failed and res contains the curl error message. All curl error codes are recalculated by adding 10

Normally dyn api provides no output besides printing error messages to stderr if the request failed.

Since dyn api doesn’t return output, you don’t pipe or save to variables the output of your requests. If you have just run a request to API using dyn api command, its output is stored in the variable res. Errors are also saved into this variable in case you want to see the complete response of a failed request

If you want to view or process the response from the API in a more friendly format, you can pipe the variable res thru the function json2bash provided by bash+

For your own functions, you can use dyn_msg command to print info/error messages The convention in bash+ is to always send messages to stderr by using 1>&2 redirection

Clone this wiki locally