187

I have some experience using linux but none using nginx. I have been tasked with researching load-balancing options for an application server.

I have used apt-get to install nginx and all seems fine.

I have a couple of questions.

What is the difference between the sites-available folder and the conf.d folder. Both of those folders were INCLUDED in the default configuration setup for nginx. Tutorials use both. What are they for and what is the best practice?

What is the sites-enabled folder used for? How do I use it?

The default configuration references a www-data user? Do I have to create that user? How do I give that user optimal permissions for running nginx?

Jesse Nickles
  • 250
  • 1
  • 12
Seth Spearman
  • 2,031
  • 2
  • 13
  • 10
  • 1
    Try to avoid scope creep when asking a question; `www-data` is a separate topic. Most operating systems define a separate user with lower permissions that the process can run as after binding to port 80 as root. It's defined in the config file. Apply basic security practices from there; don't let the user write to anything the webserver shouldn't need to write to, don't let other users write to the files unless it's deliberate. – Andrew B Jul 31 '13 at 15:14

5 Answers5

147

The sites-* folders are managed by nginx_ensite and nginx_dissite. For Apache httpd users who find this with a search, the equivalents is a2ensite/a2dissite.

The sites-available folder is for storing all of your vhost configurations, whether or not they're currently enabled.

The sites-enabled folder contains symlinks to files in the sites-available folder. This allows you to selectively disable vhosts by removing the symlink.

conf.d does the job, but you have to move something out of the folder, delete it, or make changes to it when you need to disable something. The sites-* folder abstraction makes things a little more organized and allows you to manage them with separate support scripts.

(unless you're like me, and one of many debian admins who just managed the symlinks directly, not knowing about the scripts...)

Andrew B
  • 31,858
  • 12
  • 90
  • 128
  • 16
    Did I get something wrong? Not understanding the downvote. – Andrew B Aug 09 '13 at 13:27
  • 1
    i am curious is this built into nginx? i installed manually https://github.com/perusio/nginx_ensite – lfender6445 Dec 22 '16 at 02:39
  • 29
    It's important to note that `sites-available|sites-enabled` is a Debian-ism and is not something that nginx or Apache do. It was probably quite useful in the past, but its utility is somewhat limited in an age of configuration management and containers. – Michael Hampton Dec 22 '16 at 17:43
  • 1
    Can you comment how configuration management and containers limits the utility of sites-available|sites-enabled? – karthik v Feb 23 '19 at 22:46
  • I wish the OP had not included information specific to nginx_ensite and nginx_dissite as it's a 3rd party tool to manage those. – hyde Mar 01 '19 at 01:14
  • 9
    @karthikvee the point is that nowadays servers often appear as ephemerical containers that serve only a single website/service, so this can be included in `nginx.conf` without any loss of readability. This is opposite to the approach from a few years ago when servers would normally store tens of websites. – adamczi Jul 07 '19 at 21:37
63

I would like to add to the previous answers that the most important is not how you call the directories (though that is a very useful convention), but what you actually put in nginx.conf. Example configuration:

http {
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*.conf;
    include /etc/nginx/sites-enabled/my_own_conf;
...
}

The only directive used here is include, so there is no internal difference between e.g. conf.d/ and sites-enabled/.

From the documentation above:

Syntax:     include file | mask;
Default:    —
Context:    any

Includes another file, or files matching the specified mask, 
into configuration. Included files should consist of 
syntactically correct directives and blocks.

So, to answer the original question: there is no internal difference, and you may use them in the best way you can, remembering advice from the other answers. And please, don't forget to choose the 'right' answer.

Yaroslav Nikitenko
  • 765
  • 5
  • 13
  • 3
    Right, `sites-enabled` has been somewhat invented by some ditribution, fuzzing around as an annoying intermediate does. Go grab nginx from [the official source](http://nginx.org/en/download.html): you will get an up-to-date product, as well as getting rid of this configuration crap/hell. – Bernard Rosset Apr 04 '16 at 16:10
  • 2
    This explains why there is not one single reference of this name convention on the official Nginx documentation. It is a third party project! https://github.com/perusio/nginx_ensite – AxeEffect May 24 '17 at 10:19
59

What's Going On?

You must be using Debian or Ubuntu, since the evil sites-available / sites-enabled logic is not used by the upstream packaging of nginx from http://nginx.org/packages/.

In either case, both are implemented as a configuration convention with the help of the standard include directive in /etc/nginx/nginx.conf.

Here's a snippet of /etc/nginx/nginx.conf from an official upstream package of nginx from nginx.org:

http {
    …
    include /etc/nginx/conf.d/*.conf;
}

Here's a snippet of /etc/nginx/nginx.conf from Debian/Ubuntu:

http {
    …
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

So, from the point of view of NGINX, the only difference would be that files from conf.d get to be processed sooner, and, as such, if you have configurations that silently conflict with each other, then those from conf.d may take precedence over those in sites-enabled.

Best Practice Is conf.d.

You should be using /etc/nginx/conf.d, as that's a standard convention, and should work anywhere.

If you need to disable a site, simply rename the filename to no longer have a .conf suffix, very easy, straightforward and error-proof:

sudo mv -i /etc/nginx/conf.d/default.conf{,.disabled}

Or the opposite to enable a site:

sudo mv -i /etc/nginx/conf.d/example.com.conf{.disabled,}

Avoid sites-available & sites-enabled At All Costs.

I see absolutely no reason to be using sites-available / sites-enabled:

  • Some folks have mentioned nginx_ensite and nginx_dissite scripts — the names of these scripts are even worse than the rest of this debacle — but these scripts are also nowhere to be found — they're absent from the nginx package even in Debian (and probably in Ubuntu, too), and not present in a package of their own, either, plus, do you really need a whole non-standard third-party script to simply move and/or link the files between the two directories?!

  • And if you're not using the scripts (which is, in fact, a smart choice as per above), then there comes the issue of how do you manage the sites:

  • Do you create symbolic links from sites-available to sites-enabled?

  • Copy the files?

  • Move the files?

  • Edit the files in place in sites-enabled?

The above may seem like some minor issues to tackle, until several folks start managing the system, or until you make a quick decision, only to forget about it months or years down the line…

Which brings us to:

  • Is it safe to remove a file from sites-enabled? Is it soft link? A hard link? Or the only copy of the configuration? A prime example of configuration hell.

  • Which sites have been disabled? (With conf.d, just do an inversion search for files not ending with .conf — find /etc/nginx/conf.d -not -name "*.conf", or use grep -v.)

Not only all of the above, but also note the specific include directive used by Debian/Ubuntu — /etc/nginx/sites-enabled/* — no filename suffix is specified for sites-enabled, unlike for conf.d.

  • What this means is that if one day you decide to quickly edit a file or two within /etc/nginx/sites-enabled, and your emacs creates a backup file like default~, then, suddenly, you have both default and default~ included as active configuration, which, depending directives used, may not even give you any warnings, and cause a prolonged debugging session to take place. (Yes, it did happen to me; it was during a hackathon, and I was totally puzzled of why my conf wasn't working.)

Thus, I'm convinced that sites-enabled is pure evil!

oczkoisse
  • 105
  • 3
cnst
  • 12,948
  • 7
  • 51
  • 75
  • 1
    In addition to all the above, apparently, it's also very common to create incorrect symlinks! https://stackoverflow.com/a/14107803/1122270 Just in case you didn't think `sites-enabled` was evil enough! – cnst Aug 27 '17 at 21:31
  • Or, sometimes, it may so happen that someone decides to edit the files in `sites-enabled`, yet then another person decides to disable it by deleting it, possibly thinking it was just a symlink, requiring subsequent memory dump of nginx heap to recover the conf file: https://stackoverflow.com/q/45852224/1122270 – cnst Sep 05 '17 at 18:01
  • 2
    I have to disagree with the assertions about `sites-available` and `sites-enabled`; it is important to be able to prepare config files outside of the 'live' pickup directory such that if nginx were reloaded or restarted that it wouldn't pick up partial config files. It can also be useful to keep config files which are no longer in active use. Creating symlinks isn't a particularly difficult task if you have experience enough to manage nginx in the first place, IMO. – BE77Y Sep 22 '17 at 07:47
  • 1
    @BE77Y you are taking a more complicated approach. In programming, it is considered best practice to completely remove unused code, not just disable or comment it out; I see no reason why DevOps should be any different — if a config is no longer needed, remove it (it should still exist in your VCS). Same with partial conf files — why would you edit them enabled and have nginx reloaded behind your back? (`USR1`, which re-opens logs, doesn't reload conf.) I find your symlink "experience" comments misdirected — the issue is a matter of consistency, which has little to do with experience. – cnst Sep 22 '17 at 22:18
  • 1
    I see where our disagreement stems from if you are going to analogies from programming; I consider this systems administration. In any case my fundamental disagreement was with your “avoid at all costs” rhetoric - which I think it’s fair to say is a smidge hyperbolic - particularly if you feel that it’s “complicated”. – BE77Y Sep 22 '17 at 22:31
  • 4
    @BE77Y I stand by my "avoid at all costs" rhetoric, and I think your argument is inconsistent (plus, I don't see why you feel that system administration is different to programming here). Every single use-case you've mentioned is easily possible without the `sites-{available,enabled}/*`, with `conf.d/*.conf` alone, without a way to have it X different ways, for a future sysadmin to have to figure it out. It seems that you are suggesting that adding complication is a good thing? What exactly do you appreciate about this extra complexity that provides no extra benefit as outlined above? – cnst Sep 22 '17 at 23:24
  • 6
    It’s clear that a) this is not the appropriate medium for this discussion and perhaps even more importantly, b) it’s likely to be fruitless in any case. Let’s agree to disagree. – BE77Y Sep 22 '17 at 23:26
  • 4
    Approaching this in 2020, I personally feel that there must be a reason that when NGINX is installed on a CentOS 7 server it only includes the `conf.d` directory. Being used to endlessly self-educating using Apache on Ubuntu with vhosts being defined within the `sites-*` directories, NGINX seems to be geared towards more minimalist methodologies. I often find myself having to write way less code in the `.conf` files, as well. Sometimes simpler is better and even though organizing is a key factor, there always seem to be other approaches that won't make it such a critical priority to do so. – Steven Ventimiglia May 17 '20 at 04:48
38

Typically, the sites-enabled folder is used for virtual host definitions, while conf.d is used for global server configuration. If you're supporting multiple web sites -- i.e., virtual hosts -- then each one gets its own file, so you can enable and disable them very easily by moving files in and out of sites-enabled (or creating and removing symlinks, which is probably a better idea).

Use conf.d for things like module loading, log files, and other things that are not specific to a single virtual host.

The default configuration references a www-data user? Do I have to create that user?

You should have nginx running as a non-root user. This is in some cases named www-data, but you can name it anything you want.

How do I give that user optimal permissions for running nginx?

I'm less certain of the answer to this question (I'm not running nginx at the moment), but if it's anything like Apache the answer is that the www-data user only needs read permissions to any static files (and read+execute on directories) that you're serving, or read/execute permissions on things like CGI scripts, and no permissions anywhere else.

larsks
  • 41,276
  • 13
  • 117
  • 170
  • 1
    having a dedicated user for running web server is also important due to disable login capability for this user by removing valid shell record. – DukeLion Aug 09 '13 at 13:02
  • > 'You should have nginx running as a non-root user' - could you elaborate more about this? – lfender6445 Dec 22 '16 at 02:31
  • 1
    Running as an unprivileged user is a way of containing the damage that could result from a remote compromise. If you are running a webserver as `root` and there is a remote compromise of some sort, the attacker immediately has full access to the system. When running as an unprivileged user, administrative access would only be available in combination with some sort of local exploit. – larsks Dec 22 '16 at 16:10
1

With respect to containers [Docker]

As mentioned in a comment, the sites-* abstraction does not make sense when using containers.

It's important to note that sites-available|sites-enabled is a Debian-ism and is not something that nginx or Apache do. It was probably quite useful in the past, but its utility is somewhat limited in an age of configuration management and containers. – Michael Hampton Dec 22 '16 at 17:43

Allow me to clarify this.

Note that the current (1.21.6) NGINX Docker is built on Debian unless you specify Alpine instead. The Debian image does not use the sites-* abstraction; it is built from source (this makes sense).

So first of all, if you want to use sites-* then there are more lines of code. Creation of sites-* folders and symlinks, and editing of the default nginx.conf (or worse, checking one in that will not be updated when you upgrade your NGINX version).

If you want to keep your confs in git and have a fully reproducible build, then you commit the current state of your confs and let CI/CD do a deployment. This means that if you decided to use sites-* despite requiring more code, then you have to edit the Dockerfile or similar to adjust the symlinks that are created to enable/disable sites.

I say this

and want to keep your confs in git and have a fully reproducible build

because you could start a container that uses sites-*, log in to your server, and execute commands on the running container to manage the symlinks. In fact, this is the only way using sites-* makes sense with containerization. But with this workflow, the current state is only kept in the container (not in git, and starting a new container from the image will alter the enabled sites).

With the full conf.d approach, all you have to do is git mv mysite.com.conf mysite.com.conf.disabled and push the changes. Personally, I would rather push a rename commit than either editing the Dockerfile or logging in to a server to exec symlink commands.

So for writing less code, keeping the current state in git, and slightly more automation, I would recommend the pure conf.d approach when it comes to containers.

Ders
  • 111
  • 4