Slides for the December 2016 pfSense Hangout video

1. Console Menu
December 2016 Hangout
Jim Pingle

2. About this Hangout
● Project News
● Console Menu Access & Setup
– Keyboard/Video Console
– Serial Console
– SSH
● Console Menu Options
● Using the PHP Shell
● Using the tcsh Shell

3. Project News
●
SG-1000 shipping, all backorders shipped!
– Development and improvements are still ongoing
– USB OTG port is now bootable with new snapshots
●
Switch framework from SG-1000 (Interfaces > Switches) to be used
for future products including large numbers of switch ports
– https://blog.pfsense.org/?p=2174
●
Enterprise Support coming in January
– Three choices, yearly, per-device, non-incident
●
pfSense Code Audit
– Audit was performed by an independent consulting firm
– Results were excellent
– Full details will be posted soon on the Netgate & pfSense blogs

4. Console Menu Requirements
● Physical Keyboard/Video console
– Firewall hardware must have video output, keyboard attached
● Serial Console
– Device must have a serial port or similar console port
● Devices with a traditional DB9 or RJ45 style serial port must use COM1
● Null modem serial cable or adapter
● Client must also have a serial port or USB/Serial converter
– http://store.netgate.com/Serial-NULL-Modem-RS232-Cable-Kit-P2165.aspx
– SG devices have a Micro USB console port that acts as a USB/Serial converter on COM2
● Only a micro-USB cable, such as an Android device cable, is required
– Serial console must be enabled on pfSense
● Defaults to enabled for SG devices or devices installed from the serial memstick
● Enabled in the GUI for others
● SSH
– SSH must be enabled on the firewall
– Firewall rules must allow access
● All types:
– When setting up a terminal, default size is usually 24 rows, 80 columns
● This size works best for the installer
– For general use after installation, we recommend wider & taller terminals to show more information
● Example: 32 rows, 132 columns.

5. Physical Console Configuration
●
Video console is always enabled if present
●
Serial console may need to be enabled manually unless it is the only console
●
System > Advanced, Admin Access tab
– Serial Communications section
● Serial Terminal, check to enable
– Box is hidden for devices that only have serial or which have serial forced on
●
Serial Speed
– No reason to use anything other than 115200 these days
● Primary Console
– Kernel boot messages will go to all configured hardware consoles (video, serial)
– Once the kernel passes off control to the OS boot scripts, only the primary console will receive output (e.g.
pfSense boot output)
– If the output stops after “Mounting root...” without a prompt, odds are you are not looking at the primary
console
– If an error is encountered during boot, such as interfaces need reassigned, only the primary console can be
used to correct the problem
– After bootup completes, all consoles receive a menu

6. SSH Console Access Setup
●
System > Advanced, Admin Access tab, Secure Shell section
●
Or use console menu option 14 if you have access to the video or serial console
●
Check Enable Secure Shell
– The firewall will generate SSH keys for the ssh daemon, which can take some time
●
On SG-1000, this process can take about a minute and a half
●
Authentication Method
– Unchecked, passwords can be used
●
All account passwords should be strong!
● Do not expose SSH to the Internet with password authentication allowed!
– Checked, ssh keys are required for all accounts
●
Immune to brute force attacks but requires more complex setup and management
●
Keys must be generated on the client (e.g. with ssh-keygen ) and then pasted into the account settings
●
SSH port, defaults to 22
– Moving the port does not offer a significant security advantage on its own
●
Add firewall rules to allow access
– Do not expose SSH to the world if you can help it!

7. Accessing the Console Menu
Keyboard/Video
● Turn on the monitor, use the keyboard (simple)
● Switch to the KVM port, etc
● May also be accessible using IPMI, DRAC, iLO
or similar, depending on the hardware

8. Accessing the Console Menu
Serial Console
●
Connect the serial cable to the client
– If it is a USB/Serial cable, ensure it was detected properly by the OS
– Install drivers if necessary
●
Locate the proper client serial port
– On Windows, Check device manager
● PC Name > Ports (COM & LPT), [Name/Type] (COMx)
● Physical DB9 port is likely COM1, maybe COM2
● Typically COM3, COM4, or COM5 for USB
– Linux
● Check log/dmesg output, most likely it is /dev/ttyUSBx
– FreeBSD
● Check log/dmesg output, most likely is /dev/cuaUx
– MAC
● Varies by serial cable OEM/type
● SG devices use /dev/cu.SLAB_USBtoUART

9. Accessing the Console Menu
Serial Console
● Speed must match the speed configured on the previous page
● Client serial port settings:
– Most clients use these settings by default, such as PuTTY and
screen
– 8 data bits
– No parity
– 1 stop bit
– Flow Control: XON/XOFF or disabled
● RTS/CTS flow control must not be used!
● See also:
https://portal.pfsense.org/docs/manuals/reference/sg-series-se
rial-console.html

10. Accessing the Console Menu
Serial Console
●
Windows
– Serial clients: PuTTY or SecureCRT
●
PuTTY Download URL: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
●
Open PuTTY
– Select Serial for Connection Type
– Enter the COM port in Serial Line, such as COM3, COM5, etc.
– DO NOT USE HYPERTERMINAL!
●
Linux
– Serial clients: screen, PuTTY, minicom, or dterm,
– sudo screen /dev/ttyUSB0 115200
●
FreeBSD
– Serial clients: screen, cu, or tip
– sudo screen /dev/cuaU0 115200
●
MAC
– Serial clients: screen, Zterm, or cu
– sudo screen /dev/cu.SLAB_USBtoUART 115200
– May need -U passed to screen to work around character encoding issues

11. Accessing the Console Menu
SSH
● Windows
– Clients: PuTTY, SecureCRT, mRemoteNG, cygwin CLI ssh, 10AU+Ubuntu Bash CLI ssh
● Linux/FreeBSD
– Clients: PuTTY, CLI ssh, PAC
● MAC
– Clients: Terminal, iTerm2
● Client must be recent and support the key exchange, cipher, and MAC requirements on
pfSense
● From the CLI it’s the same on any OS:
– ssh username@192.168.1.1
● GUI clients must be set to connect to the firewall IP address on the correct port, with
the expected username
● For key-based authentication, consult the client documentation
● If the client does not work, update it and try again
– Current versions of PuTTY, SecureCRT, and others work well, older versions do not

12. Console Menu Tasks
● 0) Logout (SSH Only)
– Ends the current SSH session
– Pressing enter without entering an option will also
close the SSH session, as will using CTRL-D

13. Console Menu Tasks
● 1) Assign Interfaces
– Prompts the user to wipe the existing interface configuration and
start over with new interface assignments
– This is the same procedure that is triggered during boot when the
available physical/virtual interfaces do not match the assigned
interfaces
– Can create VLANs, but not other special interface types (e.g. LAGG)
– Lists all available interfaces and VLANs for assignment
● For physical interfaces, MAC addresses are printed in the list
– At least one interface must be assigned (WAN)
– Press enter without typing an interface name to stop

14. Console Menu Tasks
● 2) Set interface(s) IP address
– Set an IP address for any firewall interface
– Can configure static addresses or DHCP
– For static addresses:
● Prompts for the IP address, subnet mask, and optional gateway
● Prompts to enable or disable DHCP service for an interface, and to set
the DHCP IP address range if it is enabled
– If the firewall GUI is configured for HTTPS, the menu prompts
to switch to HTTP in case SSL is not functional
– Enables the anti-lockout rule in case the user has been locked
out of the GUI

15. Console Menu Tasks
● 3) Reset webConfigurator Password
– Resets the admin account password back to
“pfsense”
– If the GUI authentication source is RADIUS/LDAP,
the script prompts to reset as Local Database
– If the admin account has been removed, the script
re-creates the account
– If the admin account is disabled, the script re-
enables the account

16. Console Menu Tasks
● 4) Reset to factory defaults
– Restores the system configuration back to its
factory default (/conf.default/config.xml)
– Attempts to remove non-default packages
– Does not make any filesystem changes
– A wipe and reload may be a better choice if
anything other than the configuration needs to be
reset

17. Console Menu Tasks
● 5) Reboot system
– Shuts down the firewall cleanly and performs a clean
restart
– 2.4 adds a few new options:
● Reboot normally
● Reroot
– A quicker restart that doesn’t reload the kernel
– Kills processes, remounts filesystems, runs startup sequence
● Reboot into Single User Mode
– Needs console access
● Reboot and run a filesystem check
– Runs fsck on the root slice 5x

18. Console Menu Tasks
● 6) Halt System
– Cleanly shuts down the firewall
– Stops all processes
– Synchronizes all filesystems
– Attempts to power off the firewall if the hardware is
capable
– Always use this option or its GUI equivalent when
turning off the firewall
● Never abruptly disconnect power!

19. Console Menu Tasks
● 7) Ping Host
– Sends three ICMP echo requests to a target and
displays the results
– When passed an IPv4 address or a hostname, it
uses ping
– When passed an IPv6 address it uses ping6
● 8) Shell
– Starts a tcsh shell and presents a shell prompt
– Will cover this more later

20. Console Menu Tasks
● 9) pfTop
– Invokes pfTop for a real-time view of firewall state
table activity
– Has a variety of views to help spot connections
passing a lot of data, for example
– Use 0-8 to select a view directly
– The view can be sorted in a variety of ways
– Press ? To see help which shows all of the
keyboard shortcuts

21. Console Menu Tasks
● 10) Filter Logs
– Runs (essentially) a “tail” on the filter log file
– Log entries are presented in raw format
● https://doc.pfsense.org/index.php/Filter_Log_Format_for_pf
Sense_2.2
– For a simpler real-time view, run this from the shell:
● clog -f /var/log/filter.log | filterparser.php
● 11) Restart webConfigurator
– Restarts the nginx instance that runs the WebGUI
– Usually needs option 16 run as well to restart PHP-
FPM

22. Console Menu Tasks
● 12) PHP Shell + pfSense tools
– Starts an interactive PHP shell that runs in a similar
context to the firewall GUI
– Will cover more later
● 13) Update from the console
– Attempts to run an OS update, the same as from the
GUI
● 14) Enable/Disable Secure Shell
– Toggles the state of the SSH daemon, as covered
earlier

23. Console Menu Tasks
● 15) Restore Recent Configuration
– Similar to the configuration history in the GUI
– Lists recent configuration changes and offers to restore older
configurations
– Useful for stepping back to a working configuration after a change that
had a negative impact
– Does not apply changes, needs a reboot to fully take effect
● 16) Restart PHP-FPM
– Stops and restarts the daemon which handles PHP processes for nginx
– If the GUI web server process is running but unable to execute PHP
scripts, invoke this option
– Helps restore GUI access when it fails with 5xx nginx errors such as
502 / “Bad Gateway”

24. Console Menu Tasks
● Option 99 (SG-1000 booted from SD card only)
– When running certain images on the SG-1000 loaded to an
SD card, this option is present on the menu
– When invoked, it copies the running system to the eMMC
– After it completes, power off the firewall and remove the SD
card to run from eMMC
● Hidden menu option 100
– Launches “links”, a command-line text-based web browser
and attempts to connect to the firewall GUI
– No JS support, so use is limited
– After login, press ‘g’ and go to the firewall URL /index.php

25. Using the PHP Shell
●
Obligatory “Danger this is unsupported and could break stuff” warning
●
Console menu option 12 invokes the PHP Shell
● Can interact with the configuration and the running system as a whole
● Primarily useful to developers and very advanced users
●
Runs in a context similar to the GUI
– Can read the configuration from $config, globals from $g, and so on.
– Can write the configuration if necessary
– “Apply” action is trickier, would need to call specific functions directly, so not
recommended
●
Supports session recording and playback, playback is the most useful
feature
●
pfSense ships with a number of useful default playback scripts

26. PHP Shell – Running Commands
● Type “help” for command examples and
information
● Each block of commands must be followed by
“exec” on a new line to execute the code
● Type “exit” or use CTRL-C to return to the
menu
● Example that dumps the LAN DHCP settings:
pfSense Shell: var_dump($config['dhcpd']['lan']);
pfSense Shell: exec

27. PHP Shell – Playback Scripts
● Use from option 12 with “playback
<scriptname> [options]”
● Use from the shell with: “pfSsh.php playback
<scriptname> [options]”
● Some playback scripts have options, others do
not
– Most are coded friendly enough to print a help
message if they need options that are not given

28. PHP Shell – Playback Scripts
● changepassword
– Changes the password for a user
● Username can be supplied as an optional argument, will prompt if nothing is given
– Resets account properties if it is disabled or expired
● enablecarp / disablecarp
– Enable/disable CARP functions for troubleshooting purposes, same as the GUI button
– Does not persist
● enablecarpmaint / disablecarpmaint
– Enters/exits CARP maintenance mode, same as the GUI button
– Persists across reboots
– Demotes unit, does not disable CARP
● disabledhcpd
– Removes all DHCP server configuration from all interfaces on the firewall and stops the DHCP service
● disablereferercheck
– Disables HTTP_REFERER verification
– Useful when the GUI cannot be reached due to the method used by the client

29. PHP Shell – Playback Scripts
● enableallowallwan
– Adds an “allow all” rule to the WAN, meant as a VERY temporary measure to regain access to the GUI in cases when the
LAN is unavaiable
– Primarily used with lab virtual machines that have disconnected LANs or no LAN-side client available
●
enablesshd
– Enables the SSH daemon, same as the GUI checkbox or the console menu option
● externalconfiglocator
– Invokes the external configuration locater which attempts to find a config.xml on an attached removable disk
●
gatewaystatus
– Prints the gateway status formatted for the terminal (New in 2.4)
● generateguicert
– Generates and activates a new certificate for the GUI using the current firewall hostname and other parameters
– Very useful for generating new certificates to replace old GUI certificates from 2.0.x and earlier that had generic properties,
which now cause problems in Firefox
●
gitsync
– A complex script used to copy down recent commits from github to the firewall to catch up on changes
– Primarily useful for tracking small code changes between development snapshots
– Does not update binaries, use with caution

30. PHP Shell – Playback Scripts
● installpkg / listpkg / uninstallpkg
– Manipulates packages
– Not useful on 2.3+ as using “pkg” directly has the same effect
● pfanchordrill
– Recursively searches through pf anchors and prints any NAT or firewall rules it finds
– Useful for debugging services that rely on anchors like UPnP or relayd
● pftabledrill
– Prints the contents of all pf tables (aliases, built-in tables, etc)
– Useful for finding an address across all aliases, especially with dynamic aliases (FQDNs,
URL tables, etc)
● removepkgconfig
– Removes all package configuration from config.xml but does not uninstall packages
– Can return config.xml to a usable state, but the OS packages can mismatch

31. PHP Shell – Playback Scripts
● removeshaper
– Removes all ALTQ queues and rules generated by the shaper wizard
– Useful if the ALTQ configuration is causing problems with network
connectivity and the GUI cannot be reached
● resetwebgui
– Resets the GUI theme, dashboard widgets, and menu configuration
back to default
● restartdhcpd
– Stops and starts the DHCP daemon
● restartipsec
– Reloads the strongSwan configuration for IPsec

32. PHP Shell – Playback Scripts
●
svc
– Controls services similar to Status > Services in the GUI
– playback svc <action> <service name> [service-specific options]
– The action can be stop, start, or restart.
– The service name is the name of the services as found under Status > Services. If the
name includes a space, enclose the name in quotes.
– The service-specific options vary depending on the service, they are used to uniquely
identify services with multiple instances, such as OpenVPN or Captive Portal entries.
– Examples:
● Stop bsnmpd:
– pfSsh.php playback svc stop bsnmpd
● Restart OpenVPN server with ID 1:
– pfSsh.php playback svc restart openvpn server 1
● Start the Captive Poral process for zone “Guests”:
– pfSsh.php playback svc start captiveportal Guests

33. Using the tcsh Shell
● Obligatory “Danger this is unsupported and could break stuff” warning
● A majority of common utilities are present and can be used for
troubleshooting or gathering information, among other uses
● The shell invoked from console menu option 8 is tcsh and those
familiar with FreeBSD will be at home, with some caveats
– Some common shell utilities are not present due to size and/or security
constraints
– No compiler environment
– No man/info pages
– Do not attempt to make permanent changes to daemon configurations as
they will likely be overwritten by pfSense when settings are synchronized or
at the next reboot
● Consult FreeBSD or general UNIX shell documentation for specifics

34. Using the tcsh Shell
● Bash is also available via “pkg add bash” if desired
● Do not use the firewall as a general purpose UNIX
shell server, only allow shell access to firewall
administrators
● Use the sudo package to grant non-root users
access to run programs as root
● Files can be copied to/from the firewall using scp
with the “root” user
– FileZilla or the command line scp are the best clients

35. Conclusion
● Questions?
● Ideas for hangout topics? Post on forum,
comment on the blog posts, Reddit, etc