WordPress Filesystem Abstraction FAQ

I shouldn’t have to be writing this, But as some people will know, I’m utterly sick of repeat questions.

This is a FAQ on the WordPress FileSystem abstraction which i wrote as part of the Summer of Code project to implement a Plugin Upgrader for WordPress (note: the actual upgrader in core is different from what i originally wrote, however ideas and code were lifted and put in their place by a much better coder than I), The content of this post is based on the situation as of today, 20/Feb/09, I fully expect these answers will not remain current in the years to come, But hope they provide some background information on them.

The FAQ:

What methods/transports does WordPress support for accessing the filesystem?

  1. Direct – This method uses direct file IO operations from PHP
  2. FTP – This method connects to your FTP server using the credentials supplied, and performs all IO operations that way
  3. SSH – This method uses the PHP SSH2 extension to connect to the server and manipulate the files there.

What requirements must be met for a transport to be used?

  1. Direct
    • The files which PHP creates MUST be owned by the same user as the WordPress files which have been uploaded
  2. FTP
    • The user will need to supply their FTP credentials in order for it to operate
    • The FTP code branch requires either:
      1. The PHP FTP Extension to be loaded, OR
      2. The FTP Sockets Extension to be loaded, OR
      3. The PHP Function FSockopen() to be available
    • In the case of  the Sockets or Fsockopen case, The 3rd party FTP Class “PemFTP” is used.
    • I should also mention, That this supports Secure FTP as well.
  3. SSH2
    • This was added in WordPress 2.7
    • It requires the PHP SSH2 Extension to be available, This generally requires compiling from source unless you’re lucky enough for it to be available in Pecl for your distribution.
    • Unless you’re running a Dedicated or VPS server, This is not usually available to you due to the above.

Why does my WordPress Install require my FTP Credentials? My other blog doesn’t!!

As above, The Direct Method(Which requires no credentials) only works in a very certain setup, Generally, This is only servers running with suPHP or suExec with PHP as a CGI – Servers running this exist, however, Due to hardware constraints (running these uses extra resources) most hosts which oversell do not use this method.

What can i do?

Move to a different Hoster, Or if thats not an option, Simply entering your FTP details.  You can see a item later in this FAQ for how to hard-code these settings if you want.

No, Seriously, Why cant i use the Direct method? I think i should be able to!!

Because your server configuration is not supported.

Still not taking no for an answer? Ok, Heres the problems with each of the requests people ask for:

  1. I dont want to give my FTP details, I’d rather just chmod 777 everything
    • The problem with this, Is its insecure, WordPress shouldn’t be encouraging non-secure installation methods, Yes, I realise you need to chmod your uploads directory in a few cases, And thats OK, Its a convenience,  Its annoying to have to enter credentials every time you want to upload a file..
    • Yes, WordPress could write to your files in that case, But if you read on to the next point:
  2. I should be able to use it! I’m in the group which PHP runs as! (usually the same as your web server)
    • Thats all nice and well, And that means that PHP can write to your WordPress folder, However, Its got one big gotcha, Whilst it can write to the directory, Theres an issue: The files PHP create will be owned by the webservers username, And the group will be set to that group, the files will NOT be owned by your username.
    • So what i hear you say, I dont care if its not owned by my username, Ok, 2 issues at play here now:
      • You will encounter errors upon attempting to delete the files via FTP, Simply due to the fact you do not own the files.
      • Much on the same path, Because you do not own the files, If you have a Disk quota on the webserver, some encarnations will miss your files and not count it (Hooray! I hear you yell, Thats all good and fine, But if you dont like paying for disk space, find somewhere else that will sell you the even more oversold disk space!)

My FTP Doesnt work!

Ok, This isnt too common, But sometimes PHP’ will have dodgy extensions, or configurations, infact, Its VERY common for a hoster to have a crap install of PHP, the FTP extension and CURL are common culprits for being badly configured, Unfortunately, Theres not much you can do to fix stupid hosts, other than complain.

As a work around, You can use a plugin, or a filter yourself, to work around such circumstances, While I never intended this plugin for end-users, If enough people require it, I’ll separate the needed functionality into a separate Plugin:

Introducing Core Control, Core control is a plugin which gives some extra control over certain items in WordPress, Mainly Filesystem access and HTTP access. Utilising this plugin, You can disable certain Filesystem access methods, Simply install it (The Plugin installer works great for this, Try it again if you’ve disliked the search in the past, The new Search system that went live on WordPress.org recently has improved things greatly there) and enable the Filesystem Module, Once thats done, You can simply disable the current primary transport (Hopefully its the Direct or FTP Extension method) and see if the next in line works for you:

Core Control: Disabled FTP Extension
Core Control: Disabled FTP Extension

I run FTP/SSH on a non-default port!, How can i use this with WordPress?

You can include the port in the hostname, For example, Instead of writing “dd32.id.au” i could use “dd32.id.au:4567” if i was to run on port 4567

FTP Host on alternate Port
FTP Host on alternate Port

WordPress complains that it cant find my WordPress installation!

Whilst this should be highly uncommon (I Hope!), It can happen sometimes, So read on to the next item for a solution.

I have to use the FTP/SSH method, But i dont want to enter my password every time

WordPress also supports the use of defining a selection of constants to ease the sitatuation for a few select circumstances, The supported constants (and a description of each) are:

Constant: Description: For Example:
FTP_HOST The hostname of the server to connect to define(‘FTP_HOST’, ‘dd32.id.au’); or

define(‘FTP_HOST’, ‘dd32.id.au:4567’);

FTP_USER The username to connect with define(‘FTP_USER’, ‘dd32’);
FTP_PASS The password to connect with, WordPress will remember all your other settings by default, However, It will forget your password every time you provide it (ie. it is not stored on the server), You may use this to hard-code your FTP password define(‘FTP_PASS’, ‘*************’);
FTP_PUBKEY (SSH2 only) The path to the Public Key to use for the connection define(‘FTP_PUBKEY’, ‘/var/key.pub’);
FTP_PRIKEY (SSH2 only) The path to the Private Key to use for the connection define(‘FTP_PRIKEY’, ‘/var/key’);
FTP_BASE The path on the FTP server to the WordPress files, This is absolute path in the FTP session, NOT an absolute path on the server. This should be set to the ABSPATH folder define(‘FTP_BASE’, ‘/public_html/wordpress/’);
FTP_CONTENT_DIR The path to the Content directory on the server, This is mainly useful for times when WP_CONTENT_DIR has been set, However, it should work without it in most cases. The warnings in the previous item hold true. define(‘FTP_CONTENT_DIR’, ‘/public_html/wordpress/wp-content/’);
FTP_PLUGIN_DIR The path to the Plugins directory on the server, This is mainly useful for times when WP_PLUGINS_DIR has been set, However, It should workout this in most cases. The warning for the previous items hold true. define(‘FTP_CONTENT_DIR’, ‘/public_html/wordpress/wp-content/plugins/’);

By default (And you cant change this without a plugin) WordPress saves all your entered details in the database (except password, It only stores the server address, port number, and username), If you do this once, WordPress will remember them, You may then define your password in your wp-config.php file if you so wish. But be warned, In the case where your server is compromised, OR if other users on the system can read your files (As some badly setup shared hosts are), then you may be leaving yourself wide open to an attack if anyone ever feels like it.

Why doesnt WordPress support Method XYZ for acess?

Because no-one has contributed a patch to add support for it. In WordPress 2.5, SSH was not supported, this was only added in a later version (2.7) due to someone doing enough work on it for it to be included.

Why do you see yourself as the end-all for this?

Some people might be surprised to hear(And others will not be surprised) that i get this a lot, But i do. In short, I dont, Please, Go ahead and implement your ideas, I mearly voice my opinion, My opinion does not prevent something from being included, But due to my involvement, A yes from me, Might give a bit more weight to getting something in, The same goes for all the core developers, And all those of us (me included) who regularly contribute patches to WordPress.

WordPress is a comunity effort, Due to the size of the community though, There will always be some who are more well known than others, and thats unfortunate, But its impossible for core developers to keep track of everyone. Some people have said in the past that WordPress was being developed by a core few people who did what they wanted, and didnt take others thoughts into consideration. In some ways this is true, Matt for example, Has in the past said he didnt want something to happen, Due to the respect and the weight he carries, his voice might be the deciding vote, But plenty of times will there be things commited which Matt does not agree with. Many of the core developers develop code and features which users request, even if they have no need for it themselves, I would not be surprised if the top 20% of developers of WordPress only used 10% of its features. I personally for example, Have made very little use of the Plugin upgrader and installers.

So to wrap this item up, No. Just no. I will voice my opinion, However, Take it with a grain of salt, Just like everyone elses, If you want to rip every single contribution i’ve made to WordPress out, and replace it with something you see as better, DO IT, if its better, then great, WordPress will be better off. I will do the same thing, If i see someone submit a patch which i feel could be done in a better way, Then i’ll submit a alternate patch, Quite often it’ll be a “wow, i didnt realise it could be so simple” or a “that looks much cleaner!”, or even “Isnt that what my patch does????” Deal with it, And move on.

You forgot to answer something!

You know, I probably did, So if its before the end of March 09, Add a comment, and i’ll add it to the list. Why March? Quite simple really, After a month, i’m unlikely to care enough to update it. I might write an updated post in the future which corrects things here, or updates it for whatever is in wordpress at that point in time.

I hope this has been of some use to someone out there. If it has been, Then its served its purpose.

18 thoughts on “WordPress Filesystem Abstraction FAQ”

  1. hello

    I have set up an ubuntu-based dedicated server and I was wondering why I can’t install/upgrade my plugins within WordPress.

    At least I now understand why it does not work although I still can’t have ssh2 extension and suexec or suphp working …

    Should you have valuable bookmarks on suexec/suphp/ssh2, let me know :-)


  2. hello,
    I come back to inquire !
    I have set up PHP as CGI and it works. I have installed suphp and checked the .conf file
    I have disabled the PHP apache module.
    WordPress is up & running but I still can’t have direct transport mode .
    Any help will be appreciated !

    1. You’ll need to check your file permissions maybe.

      IMO, suPHP is NOT worth it, its too much of a pain..

      You’re much better off explaining the problem, in say the WordPress support forums, and emailing me the thread, that way others may see your issues too. email me if you’re interested: wordpress@dd32.id.au

  3. To enable to direct transport on my server I chown all riles recursively to the user that php runs at. Then once the update is complete I chown it back to the ftp user. Nice and secure.

  4. I’ve posted a question over in the WP forums about using this functionality in a plugin.

    If I override the auto detection done in get_filesystem_method() by setting define(‘FS_METHOD’, ‘direct’); before initializing WP_Filesystem() everything works perfectly. If I don’t force the abstraction class to the direct IO driver it chooses FTP and fails. Would you mind checking out the forum post and providing some expert advice?


  5. Pingback: Hello world!
  6. Hi – thanks for this great write up! I hope you can help me, I’ve been trying to get wordpress to work with FTP but don’t know what’s wrong. When I enter the FTP credentials, or even the wrong FTP password or server, I get nothing but a white page.

    > My FTP Doesnt work!
    > Ok, This isnt too common, But sometimes PHP’ will have dodgy extensions, or
    > configurations, infact, Its VERY common for a hoster to have a crap install of PHP,
    > the FTP extension and CURL are common culprits for being badly configured,
    > Unfortunately, Theres not much you can do to fix stupid hosts, other than complain.

    Being that I am the host myself, what can I look for? There are no error messages that I can find, is there some way to debug what’s going wrong with FTP?

    1. OK never mind – I recompiled PHP with “–enable-ftp” and all now works like a charm, thank you again for a great article that told me where to look!

    1. As I replied by email, In cases like this, you should always recheck your FTP details from the web host. In this case, the proper hostname to use would be ‘ftp.mgnfcnt.com’, or in rare cases, ‘ftp.mgnfcnt.com:21’ might be needed.

Comments are closed.