What is the startup script?

[更新: 2019年6月27日]

This page explains the [Startup Script] function.

1. Overview

Startup script is a function for automatically executing [Startup Script] during server startup by selecting them arbitrarily at the time of creating a new server. This function enables automatic execution of the following items.

  • Execute the yum command and prepare a state in which required applications are installed.
  • Register multiple users and enable login immediately after startup.
  • Automatically specify settings in the server.

This significantly reduces setting work immediately after creating a server and simplifies construction of items such as an automatic scale-out system that combines Sacloud and API.

Supported OS

CentOS、Debian、Ubuntu、FreeBSD、RancherOS、k3OS の各バージョンです。

*This function is guaranteed to work on public archives provided by SAKURA internet.

Class

The two types of startup scripts are listed below. These types are called [Class].

Class Explanation
SHELL Startup script listed as shell script
YAML_CLOUD_CONFIG Startup script listed in YAML format

*As of April 20, 2017, the YAML_CLOUD_CONFIG class only supports RancherOS.

2. Startup script operation

When the startup script is selected at the create server screen, the following operations are performed in the server after startup.

SHELL class

  1. At the time of startup, /etc/rc.local executes /root/.sacloud-api/startup.sh.
  2. If @sacloud-apikey was used, $SACLOUD_APIKEY_ACCESS_TOKEN and $SACLOUD_APIKEY_ACCESS_TOKEN_SECRET are set as environmental variables from the “/root/.sacloud-api/notes/startup script ID_apikey” file.
  3. startup.sh executes the script (put in “/root/.sacloud-api/notes/startup script ID“) specified for [Startup Script].
  4. The script is executed and the log is output to ”/root/.sacloud-api/notes/startup script ID.log”.
  5. If @sacloud-apikey was used, when the script is finished, $SACLOUD_APIKEY_ACCESS_TOKEN and $SACLOUD_APIKEY_ACCESS_TOKEN_SECRET which were set as environmental variables are disabled, and the ”/root/.sacloud-api/notes/startup script ID_apikey” file is deleted.
  6. If each script finishes correctly (the completion code is ‘0’), an empty file named ”/root/.sacloud-api/notes/startup script ID.done” is created (if this file exists, scripts which specify @sacloud-once are not executed).
  7. Server information is stored in the /root/.sacloud-api/server.json file.

YAML_CLOUD_CONFIG class

At the time of startup, the RancherOS settings file added during disk modification is executed. For details including processing at the time of RancherOS startup, please refer to the Official site .

3. How to register the startup script

Startup scripts can be created and edited by selecting [Startup Script] from the side menu inside of the [Option] menu on the control panel.

Click the [Option] button at the top right of the control panel screen.

Select [Script] from the submenu on the left to display the startup script management window.

In the initial state, Public script, which was created by SAKURA internet in advance, is displayed. However, you can display a list of private scripts created by the user by clicking the [Private] tab at the top of the screen.

Click the [Add] button to display the [Add Startup Script] screen. At this screen, enter the name and details for the startup script.

After entering information for the startup script, click the [Create] button at the bottom right of the screen to add the script to the list of private scripts on the script management window. It now becomes possible to select the script for the [Startup Script] item of the add server screen.

4. Special tags and variables which can be used in startup scripts

The following special tags can be used in startup scripts.

*The form display function is only supported for Create new server screen.

Execution control/explanation display

This tag is for controlling execution conditions for the startup script and for setting the explanation that is displayed on the control panel.

@sacloud-once

When the following lines are added as a comment, the script is executed only once at the time of startup (only when the “/root/.sacloud-api/notes/[applicable startup script ID].done” file does not exist).

# @sacloud-once

*When this line is not listed, execution is performed every time that the server is started.
*Cannot be used for YAML_CLOUD_CONFIG class.

@sacloud-desc / @sacloud-desc-begin / @sacloud-desc-end

Specifies the character string displayed as an explanation in the startup script selection area of the create disk screen. Use for each tag is explained below.

#!/bin/bash

# @sacloud-desc-begin
#   複数行のコメントです。
#   行頭の空白文字は自動的に最適化されます。
# @sacloud-desc-end

# @sacloud-desc 1行のコメントです。
# @sacloud-desc これらのタグを複数回使用すると、全コメントが連結されます。

@sacloud-require-archive

At the create server screen, a warning is displayed when a public archive other than the specified OS was selected. By listing this tag in startup scripts which only operate in certain OS, it is possible to prevent the script from being used in an unintended environment.

Notation for this special tag is listed below.

# @sacloud-require-archive [OS種別指定子] [バージョン指定子]

*OS type specifiers are required options. Version specifiers can be arbitrarily assigned.

Specifiers for each option are listed below.

OS type specifiers

distro-centos CentOS
distro-ubuntu Ubuntu
distro-debian Debian/GNU Linux
distro-freebsd FreeBSD
distro-rancheros RancherOS
distro-k3os k3OS

Version specifiers

distro-ver-バージョン番号

Numbers (including decimal places) and wild cards can be specified in the section for version number.

Example: distro-ver-7 / distro-ver-6.*

Example description

  • Displays a warning when a public archive other than CentOS 6 is specified.
# @sacloud-require-archive distro-centos distro-ver-6.*

*This tag is only valid for public archives provided by SAKURA Cloud. For privately created archives, it does not function because judgment is not possible.
*A warning is not displayed when operation was performed from API.

@sacloud-tag

Assign tags to the resources of the startup script. Multiple tags can be set by using spaces as delineators.

# @sacloud-tag [タグ名]

この @sacloud-tag に対して @require-core、@require-memory-gib を指定することにより、サーバ作成画面で、指定した仮想コア数、メモリに満たない場合に警告を表示することができます。

Example description

  • Displaying a warning at the server creation screen unless the number of virtual cores is four or more and memory is at least 8GB
# @sacloud-tag @require-core>=4 @require-memory-gib>=8

Tag related to embedded variables and form components

Form components are displayed in the [Disk Modification] item of the create new server screen and form entry content is set for the specified variables.

Each tag is written in a shared format like the one shown below.

@sacloud-<フォーム種別> [ <オプション> [ <オプション> ... ]] <変数名> <表示ラベル> [ ex=<グレー表示テキスト> ]

Contents of variables entered in the form can be referenced using ”@@@variable name@@@.“
Options are interpreted as a shell argument, so text containing blank spaces must be enclosed in quotation marks. Only alphanumeric characters and underscores can be used in the variable name.

*Only for API key variables when using @sacloud-apikey, the normal variable format ($variable name) is used instead of the @@@variable name@@@ format. Please refer to the following examples.

# @sacloud-apikey required permission=create external_permission=cdn+bill SACLOUD_APIKEY "APIキー"

echo $SACLOUD_APIKEY_ACCESS_TOKEN > /tmp/test.log
echo $SACLOUD_APIKEY_ACCESS_TOKEN_SECRET >> /tmp/test.log

Shared options

List of options that can be specified as shared by all tags

Options Explanation
required Specification of the variable is required.
default=<character string> Value used as the default
shellarg Formats the shell argument at the time of embedding. In general, enclosed with single quotation marks (‘).
heredoc At the time of embedding, character string spanning multiple lines are formatted as a here document. The final character string is randomly generated.
indent=<integer value> The number of blank characters specified during embedding is inserted at the front of each line. Useful when embedding several lines of character strings into ansible YAML.

Form type specifier tag

This tag specifies the type of each form.

Tag Explanation
@sacloud-text Displays the character string entry section (1 line).
Special options can be used for the next item [@sacloud-text special options].
@sacloud-password Displays the password entry section (1 line).
@sacloud-textarea Displays the character string entry section (multiple lines)
@sacloud-select-begin
@sacloud-select-end
Displays a pop-up menu.
Lines enclosed by these tags are interpreted as pairs of values and display labels, and are displayed as options.
If the display label has been omitted, the value itself is used as the label.
@sacloud-checkboxes-begin
@sacloud-checkboxes-end
Displays the checkbox group.
Lines enclosed by these tags are interpreted as pairs of values and display labels, and are displayed as options.
Multiple selected values are joined by half-width spaces.
@sacloud-checkbox Displays a single checkbox.
When not selected, a blank character is used. When selected, a ”1″ is inserted instead.
@sacloud-apikey Created API keys can be selected from the list and specified.
ACCESS TOKEN is stored in the variable named $SACLOUD_APIKEY_ACCESS_TOKEN
and ACCESS TOKEN SECRET is stored in the variable named $SACLOUD_APIKEY_ACCESS_TOKEN_SECRET.
Cannot be used for the YAML_CLOUD_CONFIG class.

@sacloud-apikey special options

permission=<文字列>

Specifies the minimum required access level. Only API keys at or above the specified access level are displayed in the selection box.

The character strings listed below can be specified.

  • Disable: none
  • View resourses: view
  • Power operation: power
  • Modify settings: arrange
  • Create/delete: create

Example: permission=create

external_permission=<文字列>

Specify access permission to other required services.

Only API keys with access permission to other specified services are displayed in the select box. The character strings [bill] and [cdn] can be used.

Multiple specifications can be made by using + as a delimiter.

Example: external_permission=bill+cdn

@sacloud-text special options

Special option of the character string entry section display tag @sacloud-text

Options Explanation
maxlen=<integer value> Maximum length permitted for acceptance when evaluated as a character string
minlen=<integer value> Minimum length permitted for acceptance when evaluated as a character string
ex = <character string> Text displayed grayed-out in textboxes where information has not yet been entered
integer Enables only the entry of integer values.
min=<number> Minimum value permitted for acceptance when evaluated as a number
max=<number> Maximum value permitted for acceptance when evaluated as a number

Defined variable

Variables already defined at the time of script execution

Variable name Explanation
@@@.ID@@@ Sets the note ID.
@@@.Name@@@ The note name is set.

5. Startup script example (SHELL class)

Example of startup script created using bash script and using form variables

#!/bin/bash

# @sacloud-once
# @sacloud-text required shellarg maxlen=100 blog_title "ブログタイトル"
# @sacloud-textarea required heredoc maxlen=1000 blog_desc "説明" ex="例:さくらのblogです"
# @sacloud-text integer min=5 max=100 default=5 articles_per_page "ページあたりの記事数"
# @sacloud-radios-begin default=two-r layout "レイアウト"
#     two-r "2カラム(右サイドバー)"
#     two-l "2カラム(左サイドバー)"
#     three "3カラム"
# @sacloud-radios-end
# @sacloud-select-begin default=white theme "デザインテーマ"
#     white "白"
#     red   "赤"
#     wooden
#     crystal
# @sacloud-select-end
# @sacloud-checkboxes-begin default=history,tagcloud home_display "ホーム画面表示項目"
#     history "更新履歴"
#     profile "プロフィール"
#     tagcloud "タグクラウド"
#     twitter "Twitter"
# @sacloud-checkboxes-end
# @sacloud-checkbox default=on allow_comment "コメントを許可する"

BLOG_TITLE=@@@blog_title@@@
ARTICLES_PER_PAGE=@@@articles_per_page@@@
LAYOUT=@@@layout@@@
THEME=@@@theme@@@
HOME_DISPLAY=@@@home_display@@@
ALLOW_COMMENT=@@@allow_comment@@@

cat >/root/test.txt @@@blog_desc@@@
echo $BLOG_TITLE >> /root/test.txt

exit 0

When this script is selected at the time of server creation, a form like the one shown below is displayed.

When a server is created using the entry content shown in the diagram above, the following script with variable expansion is written to the disk.

#!/bin/bash

# @sacloud-once
# @sacloud-text required shellarg maxlen=100 blog_title "ブログタイトル"
# @sacloud-textarea required heredoc maxlen=1000 blog_desc "説明" ex="例:さくらのblogです"
# @sacloud-text integer min=5 max=100 default=5 articles_per_page "ページあたりの記事数"
# @sacloud-radios-begin default=two-r layout "レイアウト"
#     two-r "2カラム(右サイドバー)"
#     two-l "2カラム(左サイドバー)"
#     three "3カラム"
# @sacloud-radios-end
# @sacloud-select-begin default=white theme "デザインテーマ"
#     white "白"
#     red   "赤"
#     wooden
#     crystal
# @sacloud-select-end
# @sacloud-checkboxes-begin default=history,tagcloud home_display "ホーム画面表示項目"
#     history "更新履歴"
#     profile "プロフィール"
#     tagcloud "タグクラウド"
#     twitter "Twitter"
# @sacloud-checkboxes-end
# @sacloud-checkbox default=on allow_comment "コメントを許可する"

BLOG_TITLE='さくらインターネットブログ'
ARTICLES_PER_PAGE=20
LAYOUT=three
THEME=red
HOME_DISPLAY='history profile tagcloud'
ALLOW_COMMENT=1

cat >/root/test.txt <<'HD_538ed94b2dafd'
さくらインターネット株式会社のブログです。
弊社サービスの最新情報などをお届けします。
HD_538ed94b2dafd

echo $BLOG_TITLE >> /root/test.txt

exit 0

6. Startup script example (SHELL class)

Example of startup script written in the YAML format

#cloud-config
#
# @sacloud-require-archive distro-rancheros
# @sacloud-desc-begin
# RancherOSのコンソールを切り替えます。詳細は下記URLをご確認ください。
# https://docs.rancher.com/os/configuration/switching-consoles/
# @sacloud-desc-end
#
# @sacloud-select-begin required default=default console "コンソール"
# default
# alpine
# centos
# debian
# fedora
# ubuntu
# @sacloud-select-end

rancher:
  console: @@@console@@@

お客様にてスタートアップスクリプトを作成される際は、 Configuration | Rancher Labs をご確認ください。

7. List of information output to the server.json file

The put location of the server.json file differs depending on the OS.

Other than RancherOS /root/.sacloud-api/server.json
RancherOS /var/lib/rancher/conf/server.json

The following information is output to the file.

{
  "Tags": [
    "@virtio-net-pci"
  ],
  "Interfaces": [
    {
      "PacketFilter": null,
      "Switch": {
        "UserSubnet": null,
        "Subnet": {
          "Internet": {
            "BandWidthMbps": 100
          },
          "DefaultRoute": "[デフォルトゲートウェイのIPアドレス]",
          "NetworkMaskLen": 24,
          "NetworkAddress": "[ネットワークアドレス]",
          "ID": null
        },
        "Scope": "shared",
        "Name": "スイッチ",
        "ID": "[NICが接続されている先のリソースID]"
      },
      "HostName": null,
      "UserIPAddress": null,
      "IPAddress": "[NICのIPアドレス]",
      "MACAddress": "[NICMACアドレス]",
      "ID": "[NICのリソースID]"
    }
  ],
  "Disks": [
    {
      "BundleInfo": null,
      "Storage": {
        "Class": "iscsi1204",
        "MountIndex": 2100194006,
        "ID": 2100194006
      },
      "ID": "[ディスクのリソースID]",
      "Name": "[ディスクの名前]",
      "Connection": "virtio",
      "ConnectionOrder": 1,
      "ReinstallCount": 0,
      "Availability": "available",
      "SizeMB": 20480,
      "Plan": {
        "ID": 4
      }
    }
  ],
  "Zone": {
    "Region": {
      "NameServers": [
        "[ネームサーバのIP1]",
        "[ネームサーバのIP2]"
      ],
      "Description": "東京",
      "Name": "東京",
      "ID": 210
    },
    "FTPServer": {
      "IPAddress": "27.133.143.244",
      "HostName": "sac-tk1a-ssl.sakura.ad.jp"
    },
    "VNCProxy": {
      "IPAddress": "27.133.143.244",
      "HostName": "sac-tk1a-ssl.sakura.ad.jp"
    },
    "IsDummy": false,
    "Description": "東京第1ゾーン",
    "Name": "tk1a",
    "DisplayOrder": 20021001,
    "ID": 21001
  },
  "ServerPlan": {
    "ServiceClass": "cloud/plan/1core-1gb",
    "MemoryMB": 1024,
    "CPU": 1,
    "Name": "プラン/1Core-1GB",
    "ID": 1001
  },
  "ID": "[サーバのリソースID]",
  "Name": "[サーバの名前]",
  "HostName": "localhost",
  "Description": "",
  "Availability": "available",
  "ServiceClass": "cloud/plan/1core-1gb",
  "CreatedAt": "2016-05-10T10:52:59+09:00",
  "Icon": {
    "Scope": "shared",
    "Name": "CentOS",
    "URL": "https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/icon/112300511981.png",
    "ID": "112300511981"
  }
}

8. Pre-set startup scripts

SAKURA Cloud provides several convenient scripts for which settings have already been specified and which can be used immediately.

For details, please refer to the page Public Script.