Differences

This shows you the differences between two versions of the page.

--- docs:guide-developer:write-shell-script [2019/03/18 09:49] – [Check if a tool is available] use shell builtin check vgaetera
+++ docs:guide-developer:write-shell-script [2020/08/10 18:24] (current) – [Write shell scripts in OpenWrt] - Added headers to make content clearer dadillac
@@ Line 1: / Line 1: @@
-=====Write shell scripts in OpenWrt=====
+====== Write shell scripts in OpenWrt ======
-The default shell in OpenWrt is Ash, the [[wp>BusyBox|Busybox]] default shell. Most Linux distros like Ubuntu or Debian will use Bash, which is much bigger and more complex (it's around 1 MB). OpenWrt and stock firmware of routers will use Busybox which is very very light and can fit less than 512Kb, while still providing other tools you will need like **awk**, **grep**, **sed**.
-Bash and Busybox shell are similar enough for most uses. If your script is using POSIX features of Bash shell it will work in Ash shell too.
+===== The default OpenWrt shell is ash: the Almquist shell =====
-====The shebang ====
+The default [[wp>Command-line_interface|shell]] provided with //OpenWrt// is the [[wp>Almquist_shell|Almquist shell]], which is better known as the //ash shell// and is also the default [[wp>BusyBox|Busybox]] shell. Most [[wp>Linux_distribution|Linux distros]], such as [[wp>Ubuntu|Ubuntu]] or [[wp>Debian|Debian]], will use the [[wp>Bash_(Unix_shell)|Bash]] shell, which is much bigger and more complex than //ash//. For example, a typical //bash// implementation requires approximately 1 MB of disk space, which is an extravagant waste of memory/space in an embedded device.
-Scripts in OpenWrt should have **#!/bin/sh** at the first line, **#!/bin/bash** will not work.
-====Automated shell script checking====
+By contrast, //BusyBox// fits in less than 512 KB of space, and, in addition to providing the //ash// shell, it also provides many other tools you will need to manage your OpenWrt device. Some examples of the other very useful tools provided by //BusyBox// include [[wp>AWK|awk]], [[wp>grep|grep]], [[wp>sed|sed]], and [[https://en.wikibooks.org/wiki/Learning_the_vi_Editor/BusyBox_vi|vi/vim]]. Note that the stock (//i.e.// factory) firmware that ships with many routers also uses //BusyBox// for the reasons outlined here.
-Write your bash scripts with **#!/bin/sh** first line in https://www.shellcheck.net/ and it will check for features you cannot use in OpenWrt shell.
-see the https://github.com/koalaman/shellcheck/blob/master/README.md#portability
+===== OpenWrt, BusyBox, and the ash shell =====
-====Check if a tool is available====
+OpenWrt firmware uses [[wp>Busybox|BusyBox]] because it is extremely efficient with respect to 1) the size required to install it and run it in RAM, and 2) the amount of functionality it provides. Please be aware that many of the //BusyBox// implementations of common Linux/Unix tools might be more limited than their full desktop counterparts. However, //Bash// and //Busybox// shell are similar enough for the majority of daily use cases. If your script is using the [[wp>POSIX|POSIX]] features of the //Bash// shell, then it will work in the //Ash// shell, too.
+----
+**Q: Can I install a full version of Bash or other Linux CLI tools, including my favorite editor?**
+**A: Yes!** //(but there is a catch)//
+If your router supports USB storage and you choose to [[:docs:guide-user:storage:usb-drives-quickstart|install and configure a USB drive]] with your OpenWrt device, you will have much more storage space for installing programs. If you choose to go this route, then you can install the [[:packages:pkgdata:bash|bash package]] very easily. Also, OpenWrt contains many packages for installing the full versions of core Linux shell utilities, such as [[:packages:pkgdata:coreutils-basename|basename]], [[:packages:pkgdata:coreutils-cat|cat]], [[:packages:pkgdata:coreutils-rm|rm]], [[:packages:pkgdata:coreutils-sort|sort]], or [[:packages:pkgdata:coreutils-sleep|sleep]]. To get an idea of the full list of available CLI packages, visit the web page for the OpenWrt packages in the [[:packages:index:utilities|Utilities]] category and search for all packages that start with //coreutils//. Also, OpenWrt contains many full sized versions of popular [[:packages:index:utilities---editors|Linux editors]] such as [[:packages:pkgdata:nano|nano]] and vim (see [[:packages:pkgdata:vim|vim]], [[:packages:pkgdata:vim-full|vim-full]], [[:packages:pkgdata:vim-fuller|vim-fuller]]).
+**WARNING: DO NOT INSTALL ANY OF THE vim PACKAGES LINKED HERE UNLESS YOU HAVE INSTALLED A USB DRIVE.**
+To illustrate the reason for this warning, as of v19.0x, the [[:packages:pkgdata:vim-fuller|vim-fuller]] package binary is ~2.8 MB, and it will be even larger when installed.
+----
+===== The shebang Operator and Shell Scripting for OpenWrt =====
+Scripts in OpenWrt should have ''#!/bin/sh'' at the first line, ''#!/bin/bash'' will not work. For more information, refer to the [[wp>Shebang_(Unix)|shebang]] operator.
+----
+==== Can I change my default shell from ash to bash? ====
+The short answer is "//yes//", but this practice is not recommended.
+**WARNING: If you update ///etc/passwd// to change the //root// account's default shell to anything other than ''#!/bin/sh'', there is a good chance you will be unable to log in to your router via SSH**.
+If you've installed the [[:packages:pkgdata:bash|OpenWrt bash]] package on your router and then changed your default shell to ''#!/bin/bash'', you will be able to login to your device via SSH. However, the risk in doing so is that you may still lock yourself out of your device inadvertently, for example, by upgrading. The working assumption for OpenWrt is that //ash// will be the default shell. If you want to use the //bash// shell regularly, then simply run the //bash// command each time you login to your device.
+In the event you are having difficulty accessing your device via SSH, refer to the OpenWrt [[:docs:guide-user:troubleshooting:failsafe_and_factory_reset|failsafe process]].
+----
+===== Automated shell script checking =====
+Write your bash scripts with ''#!/bin/sh'' first line in [[https://www.shellcheck.net/]] and it will check for features you cannot use in OpenWrt shell.
+see the [[https://github.com/koalaman/shellcheck/blob/master/README.md#portability]]
+===== Check if a tool is available =====
 You may need to install additional command line tools in OpenWrt, as the default installation is very minimal.
 A Desktop PC Linux like Ubuntu has much more command line tools in default install.
@@ Line 21: / Line 57: @@
 time is /usr/bin/time
 </code>
+See also: [[config-scripting|Configuration in scripts]]