Writing Scripts for Linode StackScripts

What are StackScripts?

StackScripts provide Linode users with the ability to automate the deployment of custom systems on top of Linode’s default Linux distribution images. For example, every time you deploy a new Linode you might execute the same tasks, including:

• Updating your system’s software
• Installing your favorite Linux tools
• Adding a limited user account

These tasks can be automated using a StackScript that performs these actions for you as part of your Linode’s first boot process.

All StackScripts are stored in the Linode Cloud Manager and can be accessed whenever you deploy a Linode. A StackScript authored by you is an Account StackScript. While a Community StackScript is a StackScript created by a Linode community member that has made their StackScript publicly available in the Linode Cloud Manager.

In this Guide

Writing a script for use in a StackScript is generally the same as writing a script that is executed from the command line or another program. This guide includes information about the StackScript system, including the following:

• Base requirements for any script that is used as a StackScript.
• Importing an existing StackScript into your own script for code reuse.
• Accessing a StackScript’s ID number.
• Incorporating user defined fields (UDFs) into your scripts to allow for custom behavior when deploying a new Linode with a StackScript.
• Using the StackScript system’s default environment variables.

The StackScript System

StackScript Requirements

• The primary requirement for your scripts is that the interpreter needed to execute your script should exist in the Linode base image you are deploying. While Bash is an obvious choice for a script, you may choose any scripting language.

  Note

  Linode images are created using “vanilla” versions of its given distribution. Consult our Choosing a Linux Distribution guide to see list of all distributions Linode provides and to access each distribution’s corresponding websites. You can find more information on the interpreters available for each distribution on their official websites.

• When writing a script, you must use a shebang as the first line of your script. This indicates to your Linux system which interpreter to use when running the script. For example, if you are writing a Bash script, the beginning of your script should include the following line:

  1	#!/bin/bash

  Or, if you are writing a Python script, the beginning of your script should include the following line:

  1	#!/usr/bin/env python

  Alternatively, python3 can be specified with the following:

  1	#!/usr/bin/python3

Import a StackScript

Your scripts can import any Account StackScript that you own or any Community StackScript. This allows you to reuse code minimizing what you need to write in your own scripts.

• The example below shows the syntax to import another StackScript. As a result of including this line in a script, the imported StackScript is downloaded as ssinclude-[NUMBER] to your Linode. However, it must be run in order to execute its contents.

  1	<ssinclude StackScriptID="[NUMBER]">

  In Bash, you can download and run the script in the following way:

  1	source <ssinclude StackScriptID="[NUMBER]">

  If you’re scripting in another language, import the StackScript, then execute it on a second line:

  1 2	<ssinclude StackScriptID="[NUMBER]"> ./ssinclude-[NUMBER]

• Linode provides a StackScript Bash Library that includes a set of functions that perform various common tasks users might wish to execute on their Linodes. This script creates the functions, but does not run them. A new StackScript can import the Bash Library and then execute functions from it.

  Note

  Linode’s StackScript Bash Library’s ID number is 1.

Access a StackScript’s ID Number

Follow the steps in this section to find the ID number of a StackScript.

1. Log into the Linode Cloud Manager.

2. Click on the StackScripts link in the left-hand navigation menu. You are brought to the StackScripts page.

3. Click on the Account StackScripts tab or the Community StackScripts tab, depending on the type of StackScript whose ID you’d like to find

4. Click on the StackScript whose ID you’d like to access. This brings you to its StackScript detail page.

5. The StackScript detail page’s URL displays the StackScript’s ID number. You can now use this number to import the StackScript into your own script.

User Defined Fields (UDFs)

The StackScript system provides a basic markup specification that interfaces with the Linode deployment process. This syntax allows users to customize the behavior of a StackScript on a per-deployment basis. When a StackScript contains a user defined field (UDF), the Linode Cloud Manager presents the UDF as a form field. The user can then insert a corresponding custom value into the field. The values and their related variables are inserted into the script’s environment when used to deploy a new Linode.

• Use the following format to insert a UDF tag into a StackScript.

  Note

  The UDF tags are commented out to prevent execution errors, as the StackScript system parses the tags without removing them.

  1	# <UDF name="example-var" label="An example informative label for the user." default="A default value" example="An example value." />

• A UDF tag accepts the following attributes:

  Label	Description	Data Type
  name	The variable name to use within the StackScript. Note If you would like to create a masked password input field, use the word password anywhere in the UDF name attribute. required.	String. Alphanumeric and underscore, length must be less than 64 characters, and the name must be unique within the StackScript.
  label	The form field’s label to present to a user in the Linode Cloud Manager. required.	String.
  default	The UDF’s default value. If no value is specified by the user, the default value is used when deploying a new Linode with the StackScript.	String.
  example	An example input value to present to a user in the Linode Cloud Manager.	String.
  oneof	A comma separated list of acceptable single values for the field. When this attribute is provided, a dropdown menu is presented to a user with a list of values to choose from within the Linode Cloud Manager. Only one value can be selected by the user. If your StackScript uses the oneof attribute, you cannot use the manyof attribute.	Comma separated list of strings.
  manyof	A comma separated list of acceptable values for the field in any quantity, combination, or order. When this attribute is used, a dropdown menu is presented to a user. The menu lists the acceptable values they can choose from with the Linode Cloud Manager. Multiple values can be selected by the user. If your StackScript uses the manyof attribute, you cannot use the oneof attribute.	Comma separated list of strings.

Note

UDF fields are only usable by scripts written in bash.

Default Environment Variables

Linode StackScripts provide a set of default environment variables that you can use to provide your script with information about the Linode it has deployed.

Set your Environment Variables Using an External File

It is possible to set your script’s environment variables using externally hosted files. The example Bash script uses the wget utility to download two files named base.env and $IPADDR.env from the external site http://example.com/. The source command loads the downloaded files into the script.

File: StackScript

1 2 3 4 5 6 7 8 9

# [...] IPADDR=$(/sbin/ifconfig eth0 | awk '/inet / { print $2 }' | sed 's/addr://') wget http://example.com/base.env –output-document=/tmp/base.env wget http://example.com/$IPADDR.env –output-document=/tmp/system.env source /tmp/base.env source /tmp/system.env # […]

Note

The files you reference within your script must exist and be accessible via HTTP. Also, ensure that the files you host externally do not contain any sensitive information.

It is possible to set your script’s environment variables using externally hosted files. The …

StackScript Examples

Using an External Script

• If you have an existing deployment script, you can use a StackScript to deploy Linode instances with it. The following example StackScript installs PHP on the Linode, downloads an external PHP script from the URL http://example.com/deployment-script.php, makes it executable, and then runs the downloaded script.

  File: StackScript

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

  #!/bin/bash if [ -f /etc/apt/sources.list ]; then apt-get upgrade apt-get -y install php elif [-f /etc/yum.conf ]; then yum -y install php elif [-f /etc/pacman.conf ]; then pacman -Sy pacman -S --noconfirm pacman pacman -S --noconfirm php else echo "Your distribution is not supported by this StackScript" exit fi wget http://example.com/deployment-script.php --output-document=/opt/deployment-script.php chmod +x /opt/deployment-script.php ./opt/deployment-script.php

• The same script can be applied via python using the following syntax:

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

  #!/usr/bin/python3 import os.path if os.path.isfile('/etc/apt/sources.list'): os.system('sudo apt update && sudo apt -y upgrade') os.system('sudo apt -y install php php-common') elif os.path.isfile('/etc/yum.conf'): os.system('sudo yum install -y wget && sudo yum -y install php') elif os.path.isfile('/etc/pacman.conf'): os.system('pacman -Sy && pacman -S --noconfirm pacman && pacman -S --noconfirm php') else: print("Your Distribution is not supported by this StackScript") os.system('wget http://example.com/deployment-script.php --output-document=/opt/deployment-script.php') os.system('chmod +x /opt/deployment-script.php') print("StackScript Complete. Thank you!")

• If you do not want to rely on an existing external server to host your scripts for download, you can embed the bootstrapped script into the StackScript.

  File: StackScript

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

  #!/bin/bash if [ -f /etc/apt/sources.list ]; then apt-get upgrade apt-get -y install php5 elif [-f /etc/yum.conf ]; then yum -y install php elif [-f /etc/pacman.conf ]; then pacman -Sy pacman -S --noconfirm pacman pacman -S --noconfirm php else echo "Your distribution is not supported by this StackScript" exit fi cat >/opt/deployment-script.php <<EOF #!/usr/bin/php <?php print('Hello World!'); ?> EOF chmod +x /opt/deployment-script.php ./opt/deployment-script.php

• When using scripts other than bash, the underlying software supporting the scripting language may need to be installed to the operating system as part of the StackScript. This issue can be resolved by creating a simple StackScript in bash to install the required software, and then importing and executing the second StackScript which is using the desired language. For CentOS for example, this StackScript could be used to install python3, and apply a script that was previously created for it:

  1 2 3 4

  #!/bin/bash sudo dnf install -y python3 source <ssinclude StackScriptID=1111> python3 /root/ssinclude-1111

Next Steps

• See A Tutorial for Creating and Managing StackScripts to learn how to add your script to a StackScript and how to make a StackScript available to the rest of the Linode Community.

• See A Tutorial for Solving Real World Problems with Bash Scripts for a primer on creating Bash scripts.