FireBrick Custom CSS

From AAISP Support Site
Revision as of 12:06, 6 August 2017 by CecilWard (talk | contribs) (Layout tweak)

2700-small.png

Specifying custom CSS in the XML config file

You can use custom css to override the css used on the FireBrick admin pages to create your own look.

The css file is set in the config in the <http section: 

<http css-url="http://example.com/css/myfb.css">

Example - changing colours

For example, to change the header and footer bar from red to blue, create your myfb.css file as: 

/* 
   Custom css to make my FireBrick visibly different to normal ones
*/

div.header {
  background: inherit;
  background-color: #000080;
  background: -moz-linear-gradient( top, #000080 0px, #202080 100% );
  background: -webkit-gradient( linear, top, bottom, color-stop( 0%, #000080 ), color-stop( 100%, #202080 ) );
  background: -webkit-linear-gradient( top, #000080 0%, #202080 100% );
  background: -o-linear-gradient( top, #000080 0%, #202080 100% );
  background: -ms-linear-gradient( top, #000080 0%, #202080 100% );
  background: linear-gradient( top, #000080 0%, #202080 100% );
  -ms-filter: "progid:DXImageTransform.Microsoft.gradient( startColorstr = '#000080', endColorstr = '#202080' )";
}

div.footer {
  background: inherit;
  background-color: #000080;
  background: -moz-linear-gradient( top, #000080 0px, #202080 100% );
  background: -webkit-gradient( linear, left top, left bottom, color-stop( 0%, #000080 ), color-stop( 100%, #202080 ) );
  background: -webkit-linear-gradient( top, #000080 0%, #202080 100% );
  background: -o-linear-gradient( top, #000080 0%, #202080 100% );
  background: -ms-linear-gradient( top, #000080 0%, #202080 100% );
  background: linear-gradient( top, #000080 0%, #202080 100% );
  -ms-filter: "progid:DXImageTransform.Microsoft.gradient( startColorstr = '#000080', endColorstr = '#202080' )";
}
 
Custom colour header by using css

Example - changing font size

The following example CSS greatly reduces the font sizes in use in the Firebrick's web pages: 

@media screen
    {
    div.main,  div.sidemenu div.menu a,  div.topmenu,  textarea
        {
        font-size: x -small
        }
    div.footer,  div.footer *
        {
        vertical-align: top;
        padding-top: 2px;
        padding-bottom: 1px
        }
    }

This simple example has certain defects: The vertical layout of the text within the footer is slightly off, for one. The layout of the ‘Graphs’ page is quite a mess, so further work is needed.

Note that there is no space after the dot in div.main etc. This is essential; adding white space at this point would alter the meaning - see CSS selectors.

Using CSS @media

The @media screen qualifier over the given block is used in this case to restrict any preference change to only apply to the display of the Firebrick’s web pages on a screen and here the customisations do not apply when a page is printed. On the other hand, the @media print qualifier is often used to customise presentation when pages are printed, such as: getting rid of all colour, using serif fonts, changing the appearance of external links to show the actual URI, or simplifying content and hiding all unwanted or irrelevant material such as navigation lists, footers, branding.

Using CSS @import

Completely separate 'print'- and 'screen' stylesheets can be maintained in separate .css files and these files can be conditionally included by reference in a master .css file using the CSS @import directive at the top of the file with a media-type qualifier within the directive eg @import 'my_fb_print.css' print;. This qualified import form is concise compared with using the block qualifier and in theory might minimise the size of an initial CSS download, depending on the browser. A general disadvantage of @import is the latency introduced by additional http requests, some of which can not be parallelised, so this delay increases page rendering time, unless of course the CSS is already cached.

Pulling in multiple .css files

Using the CSS @import directive allows multiple .css files to be pulled in general, with or without media-type qualifiers. This gets around the restriction of only being allowed to fetch a single .css file if only more than one URI value is not permitted in the single css-url attribute.

Testing - warning

There is a danger of making the Firebrick’s web UI completely unusable with mistakes in your custom CSS. To avoid this, if you are using the Firebrick's XML config editor page, use the "Test" button rather than "Save" after making your edit, as this will roll back your change after a time limit if you are stuck.

  • In order to be prepared for recovery from a bad modification, first download a good reference copy of the XML config file in advance, and then use an http upload tool - such as curl in Unix-like environments - to upload the good saved config file to the Firebrick. See the Firebrick manual for details on config uploading by http.
  • Many web browsers have options that allow a webpage's CSS to be overridden, customised or ignored.
  • Alternatively, depending on your chosen configuration options, you may be able to log in to the Firebrick's command line even if you find the web UI unusable.

Performance degradation with external websites

To avoid introducing delays in the responsiveness of the Firebrick's web UI, choose a well-configured web server. If you are the web master of your chosen server, review the cache-friendliness settings. (Topics: 'cacheability', 'cache-control', 'ETags'.) Getting cacheability settings wrong could in theory at least mean that your Firebrick might possibly be compelled to refetch the custom CSS repeatedly. A number of excellent web-based tools are available that will check and diagnose cacheability issues of a website. If you are using the Apache web server, see the https.conf or .htaccess documentation relating to cache control options. Set long timeouts for cacheability of all CSS files and make sure that the Firebrick is not forbidden from caching the downloaded CSS. Using inappropriate short cache lifetimes, even zero, or disabling caching altogether is a fairly common and heinous practice.

Security implications

Pointing your Firebrick to a .css file that is stored in a website on the public Internet might, in theory at least, have security implications. Certainly review security of that site in general, who might have access to the site's content, FTP passwords, 'locking' features on FTP. Also consider attacks on the DNS to redirect requests to a bogus site. Man-in-the-middle attacks and ARP / ND attacks could achieve redirection at a lower level, however this is a much more general problem. Consider using TLS / SSL and use an https: URL to reference your .css file in order to prevent these possibilities, or use the data: URI scheme technique described below.

The extent of the potential outcomes that an attacker could achieve by succeeding in pulling in an evil .css file is an open question. Some versions of Microsoft Internet Explorer for Windows could cause code to be executed when triggered from within a mere .css file by the use of the powerful non standard behavior:</lang> and expression() CSS features. See MSDN articles on CSS 'behavior:' and CSS 'expression()'.

Internal inline CSS - using data URIs

To avoid having to use an external website to store your custom CSS, you can employ a data: URI - see RFC 2397. Be aware that there may be a limit on the length of URIs however, and in any event see RFC 2397 section 2.

I recommend that you should not attempt to include newlines in the inline CSS of your data URI, as this may be forbidden by the URI scheme standard. Be aware of the risk of your inline CSS containing characters that are either prohibited in data URIs, illegal in quoted strings or in XML attributes. See both the RFC for the data URI scheme and also the XML standards. Just some examples of illegal characters are ", %, &, >, newlines and there are probably various others, The simple technique of including literal CSS straight, as below, is only usable if the particular fragment of CSS does not contain any problematic characters, otherwise see the next section for a general method.

Example, straight inline CSS (exercise caution regarding prohibited characters if adapting). In the following example, line-breaks may be included for readability. These must be removed and the whole string must be entered as a single line. 

<http css-url="data:text/css,@media screen{div.main,div.sidemenu div.menu a,div.topmenu,textarea{font-size:x-small}div.footer,div.footer *{vertical-align:top;padding-top:2px;padding-bottom:1px}}"  />

Note the presence of the comma after text/css. This is essential in a data URI.

Base64-encoded data

You may use base64-encoded data URIs for safety and complete flexibility as shown in the example below. Using base64-encoding removes any risks and problems with illegal characters completely. Note again the presence of the comma, now after the keyword 'base64'. This is essential in a data URI, whether base64 is used or not.

If you are using any non-ASCII characters in your CSS text, unless you have already CSS backslash-hex-encoded them, which avoids the issue, your CSS should be Unicode text and you must first UTF-8-encode your CSS into a byte stream, before then base64-encoding those bytes. You must then also declare that your original CSS text was UTF-8 as in the example below.

In the following example, line-breaks may be included for readability. These must be removed and the whole string must be entered as a single line. 

css-url="data:text/css;charset=UTF-8;base64,QG1lZGlhIHNjcmVlbntkaXYubWFpbixkaXYuc2
lkZW1lbnUgZGl2Lm1lbnUgYSxkaXYudG9wbWVudSx0ZXh0YXJlYXtmb250LXNpemU6eC1zbWFsbH1ka
XYuZm9vdGVyLGRpdi5mb290ZXIgKnt2ZXJ0aWNhbC1hbGlnbjp0b3A7cGFkZGluZy10b3A6MnB4O3BhZ
GRpbmctYm90dG9tOjFweH19"

If you are absolutely certain that your CSS will contain only ASCII characters (i.e. those below code-point 128), then the ;charset=UTF-8 declaration can be omitted.

Retrieved from ‘http://support.aa.net.uk/index.php?title=FireBrick_Custom_CSS&oldid=12539’