Knowledge Base/Engine Yard Cloud Documentation/Customize

Use Keep Files to Customize and Maintain Configurations

Engine Yard
posted this on February 16, 2012 10:02 AM

Updated: December 7th, 2012

A keep file gives you the flexibility to modify configuration settings in specific files within the /data and /etc directories of your EBS (Amazon Elastic Block Storage) volume.

When Engine Yard’s Chef goes to create configuration files from its recipe templates, it checks the filesystem for certain files prefaced with keep. If such files exist, then the Chef recipe doesn’t create new configuration files; instead it leaves the keep files in place.

For example, if the template is about to write out a configuration file called /data/myservice.conf, Chef first looks for /data/keep.myservice.conf. If this file is found, then Chef skips writing out the template-base configuration file. And, the keep.myservice.conf file is used instead.

Files that can be keep files

These are the files that can be made into keep files.

Note: Only this subset of files in the /etc or /data directories can be made into keep files. Other files in these directories might be overwritten or ignored even if they have been prefaced with “keep”.

  • /data/#{appname}/shared/config/database.yml
  • /data/nginx/nginx.conf
  • /data/nginx/common/proxy.conf
  • /data/nginx/common/servers.conf
  • /data/nginx/common/fcgi.conf
  • /data/nginx/servers/#{appname}.rewrites
  • /data/nginx/servers/#{appname}.conf
  • /data/nginx/servers/#{appname}.ssl.conf
  • /etc/haproxy.cfg
  • /etc/conf.d/nginx
  • /etc/engineyard/collectd.conf
  • /etc/redis/redis.conf
  • /etc/monit.d/unicorn_#{appname}.monitrc
  • /etc/monit.d/#{name}.#{appname}.monitrc

Important! Risks associated with keep files

There are risks associated with keep files. Use keep files with caution.

Making a keep file effectively “freezes” the file. If your environment changes, either through changes that you apply yourself or when you upgrade to the latest Engine Yard stack, your keep files can become out-of-date and thus compromise your application.

Before making changes to a production environment, review your keep files.

Tip: Where possible, consider using an include file instead of a keep file.

To use keep files for configuration

  1. Connect to your instance via SSH.

  2. Edit the file and rename (to keep.filename.extension) any of the files listed above.

    For example, for an application name “myapp”, configure the nginx server by renaming /data/nginx/servers/myapp.conf to /data/nginx/servers/keep.myapp.conf

  3. If you make nginx.conf or database.yml into keep files, add a deploy hook to create a symlink.

    ln -nfs /data/nginx/keep.nginx.conf /data/nginx/nginx.conf 


    ln /data/#{appname}/shared/config/keep.database.yml /data/#{appname}/shared/config/database.yml
  4. Important! If you make any changes to your environment that affect your keep files, update them before rebooting your environment.

More information

For more information about...See...
SSH Connect to your instance via SSH.                                                                      
Deploy hooks Use deploy hooks.
Customizing Unicorn configuration (without keep files)                                            Customize Unicorn.

If you have feedback or questions about this page, add a comment below. If you need help, submit a ticket with Engine Yard Support.



User photo
Phil Trimble

There is a mention on this page of an 'include file' that we should use instead of a 'keep file' in certain cases but I can't seem to find any information on it when searching through the existing documentation. I might just be blind, though!

I have a few specific entries I would like to add to the generated database.yml file but I would still want the generated file to be produced in case I switch environments. I just want the additional entries added to it. I would assume that 'include.database.yml' would be how it would work but I gave it a shot and it didn't seem to work. Can this article either be updated with the 'include' info or can it have a link to the 'include' documentation?


April 10, 2013 03:24 PM
User photo
Evan Machnic
Engine Yard Inc.

Hi Phil,

An "include file" refers to one of the files that is automatically included in Nginx configuration. You can see the files that are automatically included in Nginx configuration if you look at the /data/nginx/nginx.conf file.

Referencing the database.yml question, a "keep file" can be used for this but it is better to use a custom Chef recipe. This allows the file to be generated dynamically if the host of the database should change.

If you have further questions, please create a support ticket and we can go a bit deeper.

Evan Machnic

April 11, 2013 07:09 AM