====== Consoles ======

iPXE supports multiple console types.  In the default configuration, iPXE will use the local keyboard and monitor.

You can change the console configuration by editing the file ''[[http://git.ipxe.org/ipxe.git/blob/HEAD:/src/config/console.h|config/console.h]]''.  For example, to use a serial port console you can enable the build option ''[[:buildcfg:CONSOLE_SERIAL]]'':

    #define CONSOLE_SERIAL

You can enable multiple console types.  Any output from iPXE will appear on all consoles at the same time.

===== Console types =====

==== BIOS console ====

{{ :screenshots:cmdline.png?180x100|BIOS console}}

The BIOS console uses a locally-attached keyboard and monitor for interaction with the user.  You can enable or disable the BIOS console using the build option ''[[:buildcfg:CONSOLE_PCBIOS]]''.  The BIOS console is enabled by default.

Most BIOSes assume a US keyboard layout.  You can use the ''[[:buildcfg:KEYBOARD_MAP]]'' build option to change the keyboard layout used by iPXE.  For example, to use a German keyboard layout:

    #define KEYBOARD_MAP de

==== Graphical framebuffer console ====

{{ :screenshots:background.png?200x150|Graphical framebuffer console}}

The graphical framebuffer console uses the same locally-attached keyboard and monitor as the BIOS console, but allows for higher resolutions, arbitrary colours, and background pictures.  You can enable or disable the graphical framebuffer console using the build option ''[[:buildcfg:CONSOLE_FRAMEBUFFER]]''.

To activate the graphical framebuffer console, you must use the ''[[:cmd:console]]'' command to configure the console.

To use background pictures, you must enable support for a suitable image format, such as ''[[:buildcfg:IMAGE_PNG]]''.

==== Serial port console ====

The serial port console uses a physical serial port for interaction with the user.  You can enable or disable the serial port console using the build option ''[[:buildcfg:CONSOLE_SERIAL]]''.

The default serial port configuration is to use COM1 at 115200 baud with 8 data bits, no parity, and 1 stop bit.  You can use the ''[[:buildcfg:COMCONSOLE]]'', ''[[:buildcfg:COMSPEED]]'', ''[[:buildcfg:COMDATA]]'', ''[[:buildcfg:COMPARITY]]'' and ''[[:buildcfg:COMSTOP]]'' build options in ''[[http://git.ipxe.org/ipxe.git/blob/HEAD:/src/config/console.h|config/serial.h]]'' to change the serial port configuration.  For example, to use COM2 at 9600,8n1:

{{ :clipart:nullmodem.jpeg?100x100|A null-modem cable}}

    #define COMCONSOLE COM2
    #define COMSPEED 9600
    #define COMDATA 8
    #define COMPARITY 0
    #define COMSTOP 1

Some BIOSes provide "console redirection" and "serial over LAN" features that can be used to access the BIOS console remotely.  If your BIOS is already providing console redirection, then you should not enable the iPXE serial port console, since it will interfere with the BIOS' own use of the serial port.

==== Syslog console ====

The syslog console sends output to a remote syslog server.  You can enable or disable the syslog console using the build option ''[[:buildcfg:CONSOLE_SYSLOG]]''.

The syslog server address is configured using the ''[[:cfg:syslog]]'' setting.  For example, to send log messages to 192.168.0.1:

{{ :clipart:nic.jpeg?118x111|A network card}}

    iPXE> set syslog 192.168.0.1

You will need to ensure that your syslog server is configured to accept messages received via the network.

==== Encrypted syslog console ====

The encrypted syslog console sends output to a remote syslog server via a TLS-encrypted connection.  You can enable or disable the encrypted syslog console using the build option ''[[:buildcfg:CONSOLE_SYSLOGS]]''.

The encrypted syslog server address is configured using the ''[[:cfg:syslogs]]'' setting.  For example, to send log messages to syslog.example.com:

    iPXE> set syslogs syslog.example.com

==== VMware console ====

The VMware console sends output to the VMware log file (which is usually the file ''vmware.log'' in the same directory as a virtual machine's ''.vmx'' file).  You can enable or disable the VMware console using the build option ''[[:buildcfg:CONSOLE_VMWARE]]''.

The VMware console will work only when iPXE is running inside a VMware virtual machine.

===== Console usages =====

iPXE's console output is categorised into several distinct usages:

^ ''CONSOLE_USAGE_STDOUT''    | Standard output                                                |
^ ''CONSOLE_USAGE_DEBUG''     | [[:download#debug_builds|Debugging]] messages                  |
^ ''CONSOLE_USAGE_TUI''       | Text-based user interfaces (e.g. the ''[[:cmd:config]]'' command)  |
^ ''CONSOLE_USAGE_LOG''       | [[#log_messages|Log messages]]                                 |
^ ''CONSOLE_USAGE_ALL''       | All of the above usages combined                               |

You can control which usages are associated with each console.  For example, to send debugging messages to the serial port but not to the local monitor, you could use:

    #define CONSOLE_SERIAL CONSOLE_USAGE_ALL
    #define CONSOLE_PCBIOS ( CONSOLE_USAGE_ALL & ~CONSOLE_USAGE_DEBUG )

The default usages for each console are:

|                                               ^ STDOUT  ^ DEBUG   ^ TUI     ^ LOG     ^
^ [[#bios_console|BIOS console]]                | Yes     | Yes     | Yes     | No      |
^ [[#serial_port_console|Serial port console]]  | Yes     | Yes     | Yes     | No      |
^ [[#syslog_console|Syslog console]]            | Yes     | Yes     | No      | Yes     |
^ [[#vmware_console|VMware console]]            | Yes     | Yes     | No      | Yes     |

These defaults will be used if you enable a console but do not explicitly specify any usages.  For example:

    #define CONSOLE_SERIAL

will have the same effect as

    #define CONSOLE_SERIAL ( CONSOLE_USAGE_STDOUT | CONSOLE_USAGE_DEBUG | CONSOLE_USAGE_TUI )

===== Log messages =====

{{ :clipart:disk.jpeg?120x93|A disk}}

iPXE can generate messages that can be logged to create a concise record of the boot process.  For example:

    Mar 27 11:07:29 ipxe: Downloaded "boot.php"
    Mar 27 11:07:29 ipxe: Executing "boot.php"
    Mar 27 11:07:29 ipxe: Downloaded "vmlinuz"
    Mar 27 11:07:29 ipxe: Downloaded "initrd.img"
    Mar 27 11:07:30 ipxe: Executing "vmlinuz"

You can enable or disable these messages using the build option ''[[:buildcfg:LOG_LEVEL]]''.  For example:

    #define LOG_LEVEL LOG_ALL

Log messages are sent only to consoles that have the CONSOLE_USAGE_LOG [[#console_usages|console usage]] enabled.

===== Examples =====

==== Default configuration ====

    #define CONSOLE_PCBIOS

Only the locally-attached keyboard and monitor will be used for user interaction.

No log messages will be generated.

==== Serial port enabled ====

    #define CONSOLE_PCBIOS
    #define CONSOLE_SERIAL

The default serial port (COM1 at 115200,8n1) will be used for user interaction in addition to the locally-attached keyboard and monitor.

No log messages will be generated.

==== Serial port debugging ====

    #define CONSOLE_PCBIOS ( CONSOLE_USAGE_STDOUT | CONSOLE_USAGE_TUI )
    #define CONSOLE_SERIAL

The default serial port (COM1 at 115200,8n1) will be used for user interaction in addition to the locally-attached keyboard and monitor.  Any debugging output will be sent only to the serial port.

No log messages will be generated.

==== Full console log ====

    #define CONSOLE_PCBIOS
    #define CONSOLE_SYSLOG

The locally-attached keyboard and monitor will be used for user interaction.  All console output will also be sent to a remote syslog server.

No log messages will be generated.

==== Full console log with no user interaction ====

    #undef CONSOLE_PCBIOS
    #define CONSOLE_SYSLOG

No user interaction will be available.  All console output will be sent only to a remote syslog server.

No log messages will be generated.

==== Boot progress log ====

    #define CONSOLE_PCBIOS
    #define CONSOLE_SYSLOG CONSOLE_USAGE_LOG
    #define LOG_LEVEL LOG_ALL

The locally-attached keyboard and monitor will be used for user interaction.

Log messages will be sent to a remote syslog server.