Gargoyle CLI
Posted: Sat Mar 19, 2016 10:39 pm
When something goes wrong, usually the first thing someone will ask you to troubleshoot is, "we need a system log".
They might ask you, "can we see your config files?"
Or maybe they'll ask you to modify, add or remove files from the file system on the router.
We are going to cover the basics of logging in to the router via the command line and executing common commands, and we are going to cover logging in with a GUI to edit the file system.
You will need:
- PuTTY.exe OR Terminal.app on Mac or Linux.
- Your routers IP address
- Your router password
Logging in to the command line
Using PuTTY.exe, select an SSH connection type, leave the port at default 22, and enter "root@ROUTERIP", substituting ROUTERIP for the IP address of your router.
Then click Open.
You will be asked for the password for your router. Type it in and press ENTER. Note that when you type your password, the cursor won't move and no characters will appear on screen. This is normal.
On successful login you will be greeted with the Gargoyle logo and a prompt to enter a command.
Congrats, you're in!
Common commands you may be asked to enter are:used to get the system log from the router. just copy and paste this to the person requesting it from you
used to display the contents of a file, usually asked for when we want to see what is in a config file. e.g. cat /etc/config/wireless
used to restart the wifi after making a change
we use this if we are specifically only interested in a particular setting. e.g. uci get wireless.radio0.hwmode
we use this to change a specific setting in the config. e.g. uci set wireless.radio0.hwmode=11g
we use this to save any changes we have made to configs
Any commands that work on Openwrt should work on Gargoyle. That means that the wiki pages at openwrt.org are a great resource if you need help. E.g. https://wiki.openwrt.org/doc/uci/wireless is good for self checking a wireless configuration file for problems.
NOTE: If asked for a config file, before sending it to the person make sure you have a quick flick through it to make sure that there is no sensitive information in it e.g. passwords. This is commonly the case in the wireless config file. If there is, just blank them out with something like "REMOVEDPASSWORD" so that we know you changed it.
If the command line looks too scary for you, and you're more of a point and click kind of person, then i recommend WinSCP.
Logging in to the file system
Using WinSCP, set up a "new site".
Make the protocol SCP, the host name is the ip address of your router, and the port number is 22. Username is "root" and the password is the password for your router.
Click Login and you will be greeted with the file system for the router.
If you are asked about remembering passwords, it is generally a good idea otherwise you will be constantly reentering the password to do anything.
Now you can navigate the file system just like you would on a computer. If you need to show us something, just double click to open it, and copy paste. If you need to edit something, double click to open, make the changes, hit save and close.
Common directories you might get asked to go to are:
/etc/config - where we keep all of our config files
/tmp - where some relevant temporary config files are kept
/usr/data/bwmon - where graph data is stored (and can occasionally cause boot loops)
/www - where the GUI files are kept
Putting a router into failsafe recovery mode
Watch how to do it here
Note: As of Gargoyle 1.10.0, use SSH, not Telnet, to access Failsafe
Caution should be used when poking around in either the command line or the file system. Poking and prodding the wrong files or commands can cause an unstable router. 99 times in 100, its recoverable, but you'll be frustrated with yourself.
They might ask you, "can we see your config files?"
Or maybe they'll ask you to modify, add or remove files from the file system on the router.
We are going to cover the basics of logging in to the router via the command line and executing common commands, and we are going to cover logging in with a GUI to edit the file system.
You will need:
- PuTTY.exe OR Terminal.app on Mac or Linux.
- Your routers IP address
- Your router password
Logging in to the command line
Using PuTTY.exe, select an SSH connection type, leave the port at default 22, and enter "root@ROUTERIP", substituting ROUTERIP for the IP address of your router.
Then click Open.
You will be asked for the password for your router. Type it in and press ENTER. Note that when you type your password, the cursor won't move and no characters will appear on screen. This is normal.
On successful login you will be greeted with the Gargoyle logo and a prompt to enter a command.
Congrats, you're in!
Common commands you may be asked to enter are:
Code: Select all
logread
Code: Select all
cat
Code: Select all
wifi
Code: Select all
uci get config.section.option
Code: Select all
uci set config.section.option=setting
Code: Select all
uci commit
Any commands that work on Openwrt should work on Gargoyle. That means that the wiki pages at openwrt.org are a great resource if you need help. E.g. https://wiki.openwrt.org/doc/uci/wireless is good for self checking a wireless configuration file for problems.
NOTE: If asked for a config file, before sending it to the person make sure you have a quick flick through it to make sure that there is no sensitive information in it e.g. passwords. This is commonly the case in the wireless config file. If there is, just blank them out with something like "REMOVEDPASSWORD" so that we know you changed it.
If the command line looks too scary for you, and you're more of a point and click kind of person, then i recommend WinSCP.
Logging in to the file system
Using WinSCP, set up a "new site".
Make the protocol SCP, the host name is the ip address of your router, and the port number is 22. Username is "root" and the password is the password for your router.
Click Login and you will be greeted with the file system for the router.
If you are asked about remembering passwords, it is generally a good idea otherwise you will be constantly reentering the password to do anything.
Now you can navigate the file system just like you would on a computer. If you need to show us something, just double click to open it, and copy paste. If you need to edit something, double click to open, make the changes, hit save and close.
Common directories you might get asked to go to are:
/etc/config - where we keep all of our config files
/tmp - where some relevant temporary config files are kept
/usr/data/bwmon - where graph data is stored (and can occasionally cause boot loops)
/www - where the GUI files are kept
Putting a router into failsafe recovery mode
Watch how to do it here
Note: As of Gargoyle 1.10.0, use SSH, not Telnet, to access Failsafe
Caution should be used when poking around in either the command line or the file system. Poking and prodding the wrong files or commands can cause an unstable router. 99 times in 100, its recoverable, but you'll be frustrated with yourself.